From a60174a51479e1fb5980fd15b5a361ba306b90bb Mon Sep 17 00:00:00 2001 From: Christina Holland Date: Mon, 6 Feb 2023 15:00:57 -0800 Subject: [PATCH 01/12] step 1 --- .github/workflows/check-docs.yml | 30 + docs-devsite/analytics.md | 112 +- docs-devsite/app-check.md | 28 +- docs-devsite/app.md | 197 ++- docs-devsite/auth.dependencies.md | 6 +- docs-devsite/auth.md | 1053 +++++++------ docs-devsite/database.md | 714 +++++---- docs-devsite/firestore_.md | 1331 ++++++++--------- docs-devsite/firestore_.queryconstraint.md | 6 +- docs-devsite/firestore_lite.md | 863 ++++++----- .../firestore_lite.queryconstraint.md | 6 +- docs-devsite/functions.md | 34 +- docs-devsite/installations.md | 32 +- docs-devsite/messaging_.md | 61 +- .../messaging_.notificationpayload.md | 11 - docs-devsite/messaging_sw.md | 61 +- .../messaging_sw.notificationpayload.md | 11 - docs-devsite/performance.md | 2 - docs-devsite/remote-config.md | 81 +- docs-devsite/storage.md | 194 +-- docs-devsite/storage.storageerror.md | 89 +- docs-devsite/storage.storageobserver.md | 2 +- docs-devsite/storage.uploadtask.md | 6 +- 23 files changed, 2324 insertions(+), 2606 deletions(-) create mode 100644 .github/workflows/check-docs.yml diff --git a/.github/workflows/check-docs.yml b/.github/workflows/check-docs.yml new file mode 100644 index 00000000000..f6ea11c6faf --- /dev/null +++ b/.github/workflows/check-docs.yml @@ -0,0 +1,30 @@ +name: Doc Change Check (Run yarn format locally if this fails) + +on: pull_request + +jobs: + doc-check: + name: Check if reference docs have changed + runs-on: ubuntu-latest + + steps: + - name: Checkout Repo + uses: actions/checkout@master + with: + # get all history for the diff + fetch-depth: 0 + - name: Set up Node (14) + uses: actions/setup-node@v2 + with: + node-version: 14.x + - name: Yarn install + run: yarn + - name: Run doc generation (devsite docs) + run: yarn docgen devsite + - name: Check for changes (fail if so) + run: | + cd docs-devsite + git diff --exit-code + - name: Reference documentation needs to be updated. See message below. + if: ${{ failure() }} + run: echo "Changes in this PR affect the reference docs. Run \`yarn docgen\` locally to regenerate docs and add them to this PR." \ No newline at end of file diff --git a/docs-devsite/analytics.md b/docs-devsite/analytics.md index bd6e4b69351..aaaf2d29863 100644 --- a/docs-devsite/analytics.md +++ b/docs-devsite/analytics.md @@ -16,10 +16,9 @@ Firebase Analytics | Function | Description | | --- | --- | -| function(app...) | | [getAnalytics(app)](./analytics.md#getanalytics) | Returns an [Analytics](./analytics.analytics.md#analytics_interface) instance for the given app. | | [initializeAnalytics(app, options)](./analytics.md#initializeanalytics) | Returns an [Analytics](./analytics.analytics.md#analytics_interface) instance for the given app. | -| function(analyticsInstance...) | +| [isSupported()](./analytics.md#issupported) | This is a public static method provided to users that wraps four different checks:1. Check if it's not a browser extension environment. 2. Check if cookies are enabled in current browser. 3. Check if IndexedDB is supported by the browser environment. 4. Check if the current browser context is valid for using IndexedDB.open(). | | [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | | [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | | [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.See [Track Screenviews](https://firebase.google.com/docs/analytics/screenviews). | @@ -43,17 +42,12 @@ Firebase Analytics | [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | | [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view). | | [setAnalyticsCollectionEnabled(analyticsInstance, enabled)](./analytics.md#setanalyticscollectionenabled) | Sets whether Google Analytics collection is enabled for this app on this device. Sets global window['ga-disable-analyticsId'] = true; | -| [setCurrentScreen(analyticsInstance, screenName, options)](./analytics.md#setcurrentscreen) | Use gtag config command to set screen_name. | -| [setUserId(analyticsInstance, id, options)](./analytics.md#setuserid) | Use gtag config command to set user_id. | -| [setUserProperties(analyticsInstance, properties, options)](./analytics.md#setuserproperties) | Use gtag config command to set all params specified. | -| function() | -| [isSupported()](./analytics.md#issupported) | This is a public static method provided to users that wraps four different checks:1. Check if it's not a browser extension environment. 2. Check if cookies are enabled in current browser. 3. Check if IndexedDB is supported by the browser environment. 4. Check if the current browser context is valid for using IndexedDB.open(). | -| function(consentSettings...) | | [setConsent(consentSettings)](./analytics.md#setconsent) | Sets the applicable end user consent state for this web app across all gtag references once Firebase Analytics is initialized.Use the [ConsentSettings](./analytics.consentsettings.md#consentsettings_interface) to specify individual consent type values. By default consent types are set to "granted". | -| function(customParams...) | +| [setCurrentScreen(analyticsInstance, screenName, options)](./analytics.md#setcurrentscreen) | Use gtag config command to set screen_name. | | [setDefaultEventParameters(customParams)](./analytics.md#setdefaulteventparameters) | Adds data that will be set on every event logged from the SDK, including automatic ones. With gtag's "set" command, the values passed persist on the current page and are passed with all subsequent events. | -| function(options...) | | [settings(options)](./analytics.md#settings) | Configures Firebase Analytics to use custom gtag or dataLayer names. Intended to be used if gtag.js script has been installed on this page independently of Firebase Analytics, and is using non-default names for either the gtag function or for dataLayer. Must be called before calling getAnalytics() or it won't have any effect. | +| [setUserId(analyticsInstance, id, options)](./analytics.md#setuserid) | Use gtag config command to set user_id. | +| [setUserProperties(analyticsInstance, properties, options)](./analytics.md#setuserproperties) | Use gtag config command to set all params specified. | ## Interfaces @@ -121,6 +115,21 @@ export declare function initializeAnalytics(app: FirebaseApp, options?: Analytic [Analytics](./analytics.analytics.md#analytics_interface) +## isSupported() + +This is a public static method provided to users that wraps four different checks: + +1. Check if it's not a browser extension environment. 2. Check if cookies are enabled in current browser. 3. Check if IndexedDB is supported by the browser environment. 4. Check if the current browser context is valid for using `IndexedDB.open()`. + +Signature: + +```typescript +export declare function isSupported(): Promise; +``` +Returns: + +Promise<boolean> + ## logEvent() Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. @@ -802,41 +811,41 @@ export declare function setAnalyticsCollectionEnabled(analyticsInstance: Analyti void -## setCurrentScreen() +## setConsent() -> Warning: This API is now obsolete. -> -> Use with `eventName` as 'screen\_view' and add relevant `eventParams`. See [Track Screenviews](https://firebase.google.com/docs/analytics/screenviews). -> +Sets the applicable end user consent state for this web app across all gtag references once Firebase Analytics is initialized. -Use gtag `config` command to set `screen_name`. +Use the [ConsentSettings](./analytics.consentsettings.md#consentsettings_interface) to specify individual consent type values. By default consent types are set to "granted". Signature: ```typescript -export declare function setCurrentScreen(analyticsInstance: Analytics, screenName: string, options?: AnalyticsCallOptions): void; +export declare function setConsent(consentSettings: ConsentSettings): void; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | The [Analytics](./analytics.analytics.md#analytics_interface) instance. | -| screenName | string | Screen name to set. | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | +| consentSettings | [ConsentSettings](./analytics.consentsettings.md#consentsettings_interface) | Maps the applicable end user consent state for gtag.js. | Returns: void -## setUserId() +## setCurrentScreen() -Use gtag `config` command to set `user_id`. +> Warning: This API is now obsolete. +> +> Use with `eventName` as 'screen\_view' and add relevant `eventParams`. See [Track Screenviews](https://firebase.google.com/docs/analytics/screenviews). +> + +Use gtag `config` command to set `screen_name`. Signature: ```typescript -export declare function setUserId(analyticsInstance: Analytics, id: string | null, options?: AnalyticsCallOptions): void; +export declare function setCurrentScreen(analyticsInstance: Analytics, screenName: string, options?: AnalyticsCallOptions): void; ``` ### Parameters @@ -844,107 +853,92 @@ export declare function setUserId(analyticsInstance: Analytics, id: string | nul | Parameter | Type | Description | | --- | --- | --- | | analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | The [Analytics](./analytics.analytics.md#analytics_interface) instance. | -| id | string \| null | User ID to set. | +| screenName | string | Screen name to set. | | options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | Returns: void -## setUserProperties() +## setDefaultEventParameters() -Use gtag `config` command to set all params specified. +Adds data that will be set on every event logged from the SDK, including automatic ones. With gtag's "set" command, the values passed persist on the current page and are passed with all subsequent events. Signature: ```typescript -export declare function setUserProperties(analyticsInstance: Analytics, properties: CustomParams, options?: AnalyticsCallOptions): void; +export declare function setDefaultEventParameters(customParams: CustomParams): void; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| properties | [CustomParams](./analytics.customparams.md#customparams_interface) | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | +| customParams | [CustomParams](./analytics.customparams.md#customparams_interface) | Any custom params the user may pass to gtag.js. | Returns: void -## isSupported() - -This is a public static method provided to users that wraps four different checks: - -1. Check if it's not a browser extension environment. 2. Check if cookies are enabled in current browser. 3. Check if IndexedDB is supported by the browser environment. 4. Check if the current browser context is valid for using `IndexedDB.open()`. - -Signature: - -```typescript -export declare function isSupported(): Promise; -``` -Returns: - -Promise<boolean> - -## setConsent() - -Sets the applicable end user consent state for this web app across all gtag references once Firebase Analytics is initialized. +## settings() -Use the [ConsentSettings](./analytics.consentsettings.md#consentsettings_interface) to specify individual consent type values. By default consent types are set to "granted". +Configures Firebase Analytics to use custom `gtag` or `dataLayer` names. Intended to be used if `gtag.js` script has been installed on this page independently of Firebase Analytics, and is using non-default names for either the `gtag` function or for `dataLayer`. Must be called before calling `getAnalytics()` or it won't have any effect. Signature: ```typescript -export declare function setConsent(consentSettings: ConsentSettings): void; +export declare function settings(options: SettingsOptions): void; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| consentSettings | [ConsentSettings](./analytics.consentsettings.md#consentsettings_interface) | Maps the applicable end user consent state for gtag.js. | +| options | [SettingsOptions](./analytics.settingsoptions.md#settingsoptions_interface) | Custom gtag and dataLayer names. | Returns: void -## setDefaultEventParameters() +## setUserId() -Adds data that will be set on every event logged from the SDK, including automatic ones. With gtag's "set" command, the values passed persist on the current page and are passed with all subsequent events. +Use gtag `config` command to set `user_id`. Signature: ```typescript -export declare function setDefaultEventParameters(customParams: CustomParams): void; +export declare function setUserId(analyticsInstance: Analytics, id: string | null, options?: AnalyticsCallOptions): void; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| customParams | [CustomParams](./analytics.customparams.md#customparams_interface) | Any custom params the user may pass to gtag.js. | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | The [Analytics](./analytics.analytics.md#analytics_interface) instance. | +| id | string \| null | User ID to set. | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | Returns: void -## settings() +## setUserProperties() -Configures Firebase Analytics to use custom `gtag` or `dataLayer` names. Intended to be used if `gtag.js` script has been installed on this page independently of Firebase Analytics, and is using non-default names for either the `gtag` function or for `dataLayer`. Must be called before calling `getAnalytics()` or it won't have any effect. +Use gtag `config` command to set all params specified. Signature: ```typescript -export declare function settings(options: SettingsOptions): void; +export declare function setUserProperties(analyticsInstance: Analytics, properties: CustomParams, options?: AnalyticsCallOptions): void; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| options | [SettingsOptions](./analytics.settingsoptions.md#settingsoptions_interface) | Custom gtag and dataLayer names. | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| properties | [CustomParams](./analytics.customparams.md#customparams_interface) | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | Returns: diff --git a/docs-devsite/app-check.md b/docs-devsite/app-check.md index b7895a05c96..fb1d58fe03b 100644 --- a/docs-devsite/app-check.md +++ b/docs-devsite/app-check.md @@ -16,10 +16,8 @@ Firebase App Check | Function | Description | | --- | --- | -| function(app...) | -| [initializeAppCheck(app, options)](./app-check.md#initializeappcheck) | Activate App Check for the given app. Can be called only once per app. | -| function(appCheckInstance...) | | [getToken(appCheckInstance, forceRefresh)](./app-check.md#gettoken) | Get the current App Check token. Attaches to the most recent in-flight request if one is present. Returns null if no token is present and no token requests are in-flight. | +| [initializeAppCheck(app, options)](./app-check.md#initializeappcheck) | Activate App Check for the given app. Can be called only once per app. | | [onTokenChanged(appCheckInstance, observer)](./app-check.md#ontokenchanged) | Registers a listener to changes in the token state. There can be more than one listener registered at the same time for one or more App Check instances. The listeners call back on the UI thread whenever the current token associated with this App Check instance changes. | | [onTokenChanged(appCheckInstance, onNext, onError, onCompletion)](./app-check.md#ontokenchanged) | Registers a listener to changes in the token state. There can be more than one listener registered at the same time for one or more App Check instances. The listeners call back on the UI thread whenever the current token associated with this App Check instance changes. | | [setTokenAutoRefreshEnabled(appCheckInstance, isTokenAutoRefreshEnabled)](./app-check.md#settokenautorefreshenabled) | Set whether App Check will automatically refresh tokens as needed. | @@ -48,47 +46,47 @@ Firebase App Check | --- | --- | | [AppCheckTokenListener](./app-check.md#appchecktokenlistener) | A listener that is called whenever the App Check token changes. | -## initializeAppCheck() +## getToken() -Activate App Check for the given app. Can be called only once per app. +Get the current App Check token. Attaches to the most recent in-flight request if one is present. Returns null if no token is present and no token requests are in-flight. Signature: ```typescript -export declare function initializeAppCheck(app: FirebaseApp | undefined, options: AppCheckOptions): AppCheck; +export declare function getToken(appCheckInstance: AppCheck, forceRefresh?: boolean): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) \| undefined | the [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to activate App Check for | -| options | [AppCheckOptions](./app-check.appcheckoptions.md#appcheckoptions_interface) | App Check initialization options | +| appCheckInstance | [AppCheck](./app-check.appcheck.md#appcheck_interface) | The App Check service instance. | +| forceRefresh | boolean | If true, will always try to fetch a fresh token. If false, will use a cached token if found in storage. | Returns: -[AppCheck](./app-check.appcheck.md#appcheck_interface) +Promise<[AppCheckTokenResult](./app-check.appchecktokenresult.md#appchecktokenresult_interface)> -## getToken() +## initializeAppCheck() -Get the current App Check token. Attaches to the most recent in-flight request if one is present. Returns null if no token is present and no token requests are in-flight. +Activate App Check for the given app. Can be called only once per app. Signature: ```typescript -export declare function getToken(appCheckInstance: AppCheck, forceRefresh?: boolean): Promise; +export declare function initializeAppCheck(app: FirebaseApp | undefined, options: AppCheckOptions): AppCheck; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| appCheckInstance | [AppCheck](./app-check.appcheck.md#appcheck_interface) | The App Check service instance. | -| forceRefresh | boolean | If true, will always try to fetch a fresh token. If false, will use a cached token if found in storage. | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) \| undefined | the [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to activate App Check for | +| options | [AppCheckOptions](./app-check.appcheckoptions.md#appcheckoptions_interface) | App Check initialization options | Returns: -Promise<[AppCheckTokenResult](./app-check.appchecktokenresult.md#appchecktokenresult_interface)> +[AppCheck](./app-check.appcheck.md#appcheck_interface) ## onTokenChanged() diff --git a/docs-devsite/app.md b/docs-devsite/app.md index babb7d7bd2b..d95e7430f71 100644 --- a/docs-devsite/app.md +++ b/docs-devsite/app.md @@ -18,22 +18,15 @@ This package coordinates the communication between the different Firebase compon | Function | Description | | --- | --- | -| function(app...) | | [deleteApp(app)](./app.md#deleteapp) | Renders this app unusable and frees the resources of all associated services. | -| function() | +| [getApp(name)](./app.md#getapp) | Retrieves a [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance.When called with no arguments, the default app is returned. When an app name is provided, the app corresponding to that name is returned.An exception is thrown if the app being retrieved has not yet been initialized. | | [getApps()](./app.md#getapps) | A (read-only) array of all initialized apps. | +| [initializeApp(options, name)](./app.md#initializeapp) | Creates and initializes a [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance.See [Add Firebase to your app](https://firebase.google.com/docs/web/setup#add_firebase_to_your_app) and [Initialize multiple projects](https://firebase.google.com/docs/web/setup#multiple-projects) for detailed documentation. | +| [initializeApp(options, config)](./app.md#initializeapp) | Creates and initializes a FirebaseApp instance. | | [initializeApp()](./app.md#initializeapp) | Creates and initializes a FirebaseApp instance. | -| function(libraryKeyOrName...) | -| [registerVersion(libraryKeyOrName, version, variant)](./app.md#registerversion) | Registers a library's name and version for platform logging purposes. | -| function(logCallback...) | | [onLog(logCallback, options)](./app.md#onlog) | Sets log handler for all Firebase SDKs. | -| function(logLevel...) | +| [registerVersion(libraryKeyOrName, version, variant)](./app.md#registerversion) | Registers a library's name and version for platform logging purposes. | | [setLogLevel(logLevel)](./app.md#setloglevel) | Sets log level for all Firebase SDKs.All of the log types above the current log level are captured (i.e. if you set the log level to info, errors are logged, but debug and verbose logs are not). | -| function(name...) | -| [getApp(name)](./app.md#getapp) | Retrieves a [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance.When called with no arguments, the default app is returned. When an app name is provided, the app corresponding to that name is returned.An exception is thrown if the app being retrieved has not yet been initialized. | -| function(options...) | -| [initializeApp(options, name)](./app.md#initializeapp) | Creates and initializes a [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance.See [Add Firebase to your app](https://firebase.google.com/docs/web/setup#add_firebase_to_your_app) and [Initialize multiple projects](https://firebase.google.com/docs/web/setup#multiple-projects) for detailed documentation. | -| [initializeApp(options, config)](./app.md#initializeapp) | Creates and initializes a FirebaseApp instance. | ## Interfaces @@ -83,97 +76,6 @@ deleteApp(app) ``` -## getApps() - -A (read-only) array of all initialized apps. - -Signature: - -```typescript -export declare function getApps(): FirebaseApp[]; -``` -Returns: - -[FirebaseApp](./app.firebaseapp.md#firebaseapp_interface)\[\] - -## initializeApp() - -Creates and initializes a FirebaseApp instance. - -Signature: - -```typescript -export declare function initializeApp(): FirebaseApp; -``` -Returns: - -[FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) - -## registerVersion() - -Registers a library's name and version for platform logging purposes. - -Signature: - -```typescript -export declare function registerVersion(libraryKeyOrName: string, version: string, variant?: string): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| libraryKeyOrName | string | | -| version | string | Current version of that library. | -| variant | string | Bundle variant, e.g., node, rn, etc. | - -Returns: - -void - -## onLog() - -Sets log handler for all Firebase SDKs. - -Signature: - -```typescript -export declare function onLog(logCallback: LogCallback | null, options?: LogOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| logCallback | LogCallback \| null | An optional custom log handler that executes user code whenever the Firebase SDK makes a logging call. | -| options | LogOptions | | - -Returns: - -void - -## setLogLevel() - -Sets log level for all Firebase SDKs. - -All of the log types above the current log level are captured (i.e. if you set the log level to `info`, errors are logged, but `debug` and `verbose` logs are not). - -Signature: - -```typescript -export declare function setLogLevel(logLevel: LogLevelString): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| logLevel | LogLevelString | | - -Returns: - -void - ## getApp() Retrieves a [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. @@ -218,6 +120,19 @@ const otherApp = getApp("otherApp"); ``` +## getApps() + +A (read-only) array of all initialized apps. + +Signature: + +```typescript +export declare function getApps(): FirebaseApp[]; +``` +Returns: + +[FirebaseApp](./app.firebaseapp.md#firebaseapp_interface)\[\] + ## initializeApp() Creates and initializes a [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. @@ -295,6 +210,84 @@ export declare function initializeApp(options: FirebaseOptions, config?: Firebas [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) +## initializeApp() + +Creates and initializes a FirebaseApp instance. + +Signature: + +```typescript +export declare function initializeApp(): FirebaseApp; +``` +Returns: + +[FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) + +## onLog() + +Sets log handler for all Firebase SDKs. + +Signature: + +```typescript +export declare function onLog(logCallback: LogCallback | null, options?: LogOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| logCallback | LogCallback \| null | An optional custom log handler that executes user code whenever the Firebase SDK makes a logging call. | +| options | LogOptions | | + +Returns: + +void + +## registerVersion() + +Registers a library's name and version for platform logging purposes. + +Signature: + +```typescript +export declare function registerVersion(libraryKeyOrName: string, version: string, variant?: string): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| libraryKeyOrName | string | | +| version | string | Current version of that library. | +| variant | string | Bundle variant, e.g., node, rn, etc. | + +Returns: + +void + +## setLogLevel() + +Sets log level for all Firebase SDKs. + +All of the log types above the current log level are captured (i.e. if you set the log level to `info`, errors are logged, but `debug` and `verbose` logs are not). + +Signature: + +```typescript +export declare function setLogLevel(logLevel: LogLevelString): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| logLevel | LogLevelString | | + +Returns: + +void + ## SDK\_VERSION The current SDK version. diff --git a/docs-devsite/auth.dependencies.md b/docs-devsite/auth.dependencies.md index 9112f016fa1..3a2d869ccfe 100644 --- a/docs-devsite/auth.dependencies.md +++ b/docs-devsite/auth.dependencies.md @@ -12,7 +12,7 @@ https://github.com/firebase/firebase-js-sdk # Dependencies interface The dependencies that can be used to initialize an [Auth](./auth.auth.md#auth_interface) instance. -The modular SDK enables tree shaking by allowing explicit declarations of dependencies. For example, a web app does not need to include code that enables Cordova redirect sign in. That functionality is therefore split into [browserPopupRedirectResolver](./auth.md#browserpopupredirectresolver) and [cordovaPopupRedirectResolver](./auth.md#cordovapopupredirectresolver). The dependencies object is how Auth is configured to reduce bundle sizes. +The modular SDK enables tree shaking by allowing explicit declarations of dependencies. For example, a web app does not need to include code that enables Cordova redirect sign in. That functionality is therefore split into [browserPopupRedirectResolver](./auth.md#browserpopupredirectresolver) and . The dependencies object is how Auth is configured to reduce bundle sizes. There are two ways to initialize an [Auth](./auth.auth.md#auth_interface) instance: [getAuth()](./auth.md#getauth) and [initializeAuth()](./auth.md#initializeauth). `getAuth` initializes everything using platform-specific configurations, while `initializeAuth` takes a `Dependencies` object directly, giving you more control over what is used. @@ -28,7 +28,7 @@ export interface Dependencies | --- | --- | --- | | [errorMap](./auth.dependencies.md#dependencieserrormap) | [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) | Which [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) to use. | | [persistence](./auth.dependencies.md#dependenciespersistence) | [Persistence](./auth.persistence.md#persistence_interface) \| [Persistence](./auth.persistence.md#persistence_interface)\[\] | Which [Persistence](./auth.persistence.md#persistence_interface) to use. If this is an array, the first Persistence that the device supports is used. The SDK searches for an existing account in order and, if one is found in a secondary Persistence, the account is moved to the primary Persistence.If no persistence is provided, the SDK falls back on [inMemoryPersistence](./auth.md#inmemorypersistence). | -| [popupRedirectResolver](./auth.dependencies.md#dependenciespopupredirectresolver) | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | The [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) to use. This value depends on the platform. Options are [browserPopupRedirectResolver](./auth.md#browserpopupredirectresolver) and [cordovaPopupRedirectResolver](./auth.md#cordovapopupredirectresolver). This field is optional if neither [signInWithPopup()](./auth.md#signinwithpopup) or [signInWithRedirect()](./auth.md#signinwithredirect) are being used. | +| [popupRedirectResolver](./auth.dependencies.md#dependenciespopupredirectresolver) | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | The [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) to use. This value depends on the platform. Options are [browserPopupRedirectResolver](./auth.md#browserpopupredirectresolver) and . This field is optional if neither [signInWithPopup()](./auth.md#signinwithpopup) or [signInWithRedirect()](./auth.md#signinwithredirect) are being used. | ## Dependencies.errorMap @@ -54,7 +54,7 @@ persistence?: Persistence | Persistence[]; ## Dependencies.popupRedirectResolver -The [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) to use. This value depends on the platform. Options are [browserPopupRedirectResolver](./auth.md#browserpopupredirectresolver) and [cordovaPopupRedirectResolver](./auth.md#cordovapopupredirectresolver). This field is optional if neither [signInWithPopup()](./auth.md#signinwithpopup) or [signInWithRedirect()](./auth.md#signinwithredirect) are being used. +The [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) to use. This value depends on the platform. Options are [browserPopupRedirectResolver](./auth.md#browserpopupredirectresolver) and . This field is optional if neither [signInWithPopup()](./auth.md#signinwithpopup) or [signInWithRedirect()](./auth.md#signinwithredirect) are being used. Signature: diff --git a/docs-devsite/auth.md b/docs-devsite/auth.md index f0f9029c225..022fdce5bd5 100644 --- a/docs-devsite/auth.md +++ b/docs-devsite/auth.md @@ -16,24 +16,36 @@ Firebase Authentication | Function | Description | | --- | --- | -| function(app...) | -| [getAuth(app)](./auth.md#getauth) | Returns the Auth instance associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). If no instance exists, initializes an Auth instance with platform-specific default dependencies. | -| [initializeAuth(app, deps)](./auth.md#initializeauth) | Initializes an [Auth](./auth.auth.md#auth_interface) instance with fine-grained control over [Dependencies](./auth.dependencies.md#dependencies_interface). | -| function(storage...) | -| [getReactNativePersistence(storage)](./auth.md#getreactnativepersistence) | Returns a persistence object that wraps AsyncStorage imported from react-native or @react-native-community/async-storage, and can be used in the persistence dependency field in [initializeAuth()](./auth.md#initializeauth). | -| function(auth...) | | [applyActionCode(auth, oobCode)](./auth.md#applyactioncode) | Applies a verification code sent to the user by email or other out-of-band mechanism. | | [beforeAuthStateChanged(auth, callback, onAbort)](./auth.md#beforeauthstatechanged) | Adds a blocking callback that runs before an auth state change sets a new user. | | [checkActionCode(auth, oobCode)](./auth.md#checkactioncode) | Checks a verification code sent to the user by email or other out-of-band mechanism. | | [confirmPasswordReset(auth, oobCode, newPassword)](./auth.md#confirmpasswordreset) | Completes the password reset process, given a confirmation code and new password. | | [connectAuthEmulator(auth, url, options)](./auth.md#connectauthemulator) | Changes the [Auth](./auth.auth.md#auth_interface) instance to communicate with the Firebase Auth Emulator, instead of production Firebase Auth services. | | [createUserWithEmailAndPassword(auth, email, password)](./auth.md#createuserwithemailandpassword) | Creates a new user account associated with the specified email address and password. | +| [deleteUser(user)](./auth.md#deleteuser) | Deletes and signs out the user. | | [fetchSignInMethodsForEmail(auth, email)](./auth.md#fetchsigninmethodsforemail) | Gets the list of possible sign in methods for the given email address. | +| [getAdditionalUserInfo(userCredential)](./auth.md#getadditionaluserinfo) | Extracts provider specific [AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface) for the given credential. | +| [getAuth(app)](./auth.md#getauth) | Returns the Auth instance associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). If no instance exists, initializes an Auth instance with platform-specific default dependencies. | +| [getIdToken(user, forceRefresh)](./auth.md#getidtoken) | Returns a JSON Web Token (JWT) used to identify the user to a Firebase service. | +| [getIdTokenResult(user, forceRefresh)](./auth.md#getidtokenresult) | Returns a deserialized JSON Web Token (JWT) used to identitfy the user to a Firebase service. | | [getMultiFactorResolver(auth, error)](./auth.md#getmultifactorresolver) | Provides a [MultiFactorResolver](./auth.multifactorresolver.md#multifactorresolver_interface) suitable for completion of a multi-factor flow. | | [getRedirectResult(auth, resolver)](./auth.md#getredirectresult) | Returns a [UserCredential](./auth.usercredential.md#usercredential_interface) from the redirect-based sign-in flow. | +| [initializeAuth(app, deps)](./auth.md#initializeauth) | Initializes an [Auth](./auth.auth.md#auth_interface) instance with fine-grained control over [Dependencies](./auth.dependencies.md#dependencies_interface). | | [isSignInWithEmailLink(auth, emailLink)](./auth.md#issigninwithemaillink) | Checks if an incoming link is a sign-in with email link suitable for [signInWithEmailLink()](./auth.md#signinwithemaillink). | +| [linkWithCredential(user, credential)](./auth.md#linkwithcredential) | Links the user account with the given credentials. | +| [linkWithPhoneNumber(user, phoneNumber, appVerifier)](./auth.md#linkwithphonenumber) | Links the user account with the given phone number. | +| [linkWithPopup(user, provider, resolver)](./auth.md#linkwithpopup) | Links the authenticated provider to the user account using a pop-up based OAuth flow. | +| [linkWithRedirect(user, provider, resolver)](./auth.md#linkwithredirect) | Links the [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) to the user account using a full-page redirect flow. | +| [multiFactor(user)](./auth.md#multifactor) | The [MultiFactorUser](./auth.multifactoruser.md#multifactoruser_interface) corresponding to the user. | | [onAuthStateChanged(auth, nextOrObserver, error, completed)](./auth.md#onauthstatechanged) | Adds an observer for changes to the user's sign-in state. | | [onIdTokenChanged(auth, nextOrObserver, error, completed)](./auth.md#onidtokenchanged) | Adds an observer for changes to the signed-in user's ID token. | +| [parseActionCodeURL(link)](./auth.md#parseactioncodeurl) | Parses the email action link string and returns an [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) if the link is valid, otherwise returns null. | +| [reauthenticateWithCredential(user, credential)](./auth.md#reauthenticatewithcredential) | Re-authenticates a user using a fresh credential. | +| [reauthenticateWithPhoneNumber(user, phoneNumber, appVerifier)](./auth.md#reauthenticatewithphonenumber) | Re-authenticates a user using a fresh phone credential. | +| [reauthenticateWithPopup(user, provider, resolver)](./auth.md#reauthenticatewithpopup) | Reauthenticates the current user with the specified [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) using a pop-up based OAuth flow. | +| [reauthenticateWithRedirect(user, provider, resolver)](./auth.md#reauthenticatewithredirect) | Reauthenticates the current user with the specified [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) using a full-page redirect flow. | +| [reload(user)](./auth.md#reload) | Reloads user account data, if signed in. | +| [sendEmailVerification(user, actionCodeSettings)](./auth.md#sendemailverification) | Sends a verification email to a user. | | [sendPasswordResetEmail(auth, email, actionCodeSettings)](./auth.md#sendpasswordresetemail) | Sends a password reset email to the given email address. | | [sendSignInLinkToEmail(auth, email, actionCodeSettings)](./auth.md#sendsigninlinktoemail) | Sends a sign-in email link to the user with the specified email. | | [setPersistence(auth, persistence)](./auth.md#setpersistence) | Changes the type of persistence on the [Auth](./auth.auth.md#auth_interface) instance for the currently saved Auth session and applies this type of persistence for future sign-in requests, including sign-in with redirect requests. | @@ -46,34 +58,15 @@ Firebase Authentication | [signInWithPopup(auth, provider, resolver)](./auth.md#signinwithpopup) | Authenticates a Firebase client using a popup-based OAuth authentication flow. | | [signInWithRedirect(auth, provider, resolver)](./auth.md#signinwithredirect) | Authenticates a Firebase client using a full-page redirect flow. | | [signOut(auth)](./auth.md#signout) | Signs out the current user. | -| [updateCurrentUser(auth, user)](./auth.md#updatecurrentuser) | Asynchronously sets the provided user as [Auth.currentUser](./auth.auth.md#authcurrentuser) on the [Auth](./auth.auth.md#auth_interface) instance. | -| [useDeviceLanguage(auth)](./auth.md#usedevicelanguage) | Sets the current language to the default device/browser preference. | -| [verifyPasswordResetCode(auth, code)](./auth.md#verifypasswordresetcode) | Checks a password reset code sent to the user by email or other out-of-band mechanism. | -| function(link...) | -| [parseActionCodeURL(link)](./auth.md#parseactioncodeurl) | Parses the email action link string and returns an [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) if the link is valid, otherwise returns null. | -| function(user...) | -| [deleteUser(user)](./auth.md#deleteuser) | Deletes and signs out the user. | -| [getIdToken(user, forceRefresh)](./auth.md#getidtoken) | Returns a JSON Web Token (JWT) used to identify the user to a Firebase service. | -| [getIdTokenResult(user, forceRefresh)](./auth.md#getidtokenresult) | Returns a deserialized JSON Web Token (JWT) used to identitfy the user to a Firebase service. | -| [linkWithCredential(user, credential)](./auth.md#linkwithcredential) | Links the user account with the given credentials. | -| [linkWithPhoneNumber(user, phoneNumber, appVerifier)](./auth.md#linkwithphonenumber) | Links the user account with the given phone number. | -| [linkWithPopup(user, provider, resolver)](./auth.md#linkwithpopup) | Links the authenticated provider to the user account using a pop-up based OAuth flow. | -| [linkWithRedirect(user, provider, resolver)](./auth.md#linkwithredirect) | Links the [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) to the user account using a full-page redirect flow. | -| [multiFactor(user)](./auth.md#multifactor) | The [MultiFactorUser](./auth.multifactoruser.md#multifactoruser_interface) corresponding to the user. | -| [reauthenticateWithCredential(user, credential)](./auth.md#reauthenticatewithcredential) | Re-authenticates a user using a fresh credential. | -| [reauthenticateWithPhoneNumber(user, phoneNumber, appVerifier)](./auth.md#reauthenticatewithphonenumber) | Re-authenticates a user using a fresh phone credential. | -| [reauthenticateWithPopup(user, provider, resolver)](./auth.md#reauthenticatewithpopup) | Reauthenticates the current user with the specified [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) using a pop-up based OAuth flow. | -| [reauthenticateWithRedirect(user, provider, resolver)](./auth.md#reauthenticatewithredirect) | Reauthenticates the current user with the specified [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) using a full-page redirect flow. | -| [reload(user)](./auth.md#reload) | Reloads user account data, if signed in. | -| [sendEmailVerification(user, actionCodeSettings)](./auth.md#sendemailverification) | Sends a verification email to a user. | | [unlink(user, providerId)](./auth.md#unlink) | Unlinks a provider from a user account. | +| [updateCurrentUser(auth, user)](./auth.md#updatecurrentuser) | Asynchronously sets the provided user as [Auth.currentUser](./auth.auth.md#authcurrentuser) on the [Auth](./auth.auth.md#auth_interface) instance. | | [updateEmail(user, newEmail)](./auth.md#updateemail) | Updates the user's email address. | | [updatePassword(user, newPassword)](./auth.md#updatepassword) | Updates the user's password. | | [updatePhoneNumber(user, credential)](./auth.md#updatephonenumber) | Updates the user's phone number. | | [updateProfile(user, { displayName, photoURL: photoUrl })](./auth.md#updateprofile) | Updates a user's profile data. | +| [useDeviceLanguage(auth)](./auth.md#usedevicelanguage) | Sets the current language to the default device/browser preference. | | [verifyBeforeUpdateEmail(user, newEmail, actionCodeSettings)](./auth.md#verifybeforeupdateemail) | Sends a verification email to a new email address. | -| function(userCredential...) | -| [getAdditionalUserInfo(userCredential)](./auth.md#getadditionaluserinfo) | Extracts provider specific [AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface) for the given credential. | +| [verifyPasswordResetCode(auth, code)](./auth.md#verifypasswordresetcode) | Checks a password reset code sent to the user by email or other out-of-band mechanism. | ## Classes @@ -144,7 +137,6 @@ Firebase Authentication | [browserLocalPersistence](./auth.md#browserlocalpersistence) | An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type LOCAL using localStorage for the underlying storage. | | [browserPopupRedirectResolver](./auth.md#browserpopupredirectresolver) | An implementation of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) suitable for browser based applications. | | [browserSessionPersistence](./auth.md#browsersessionpersistence) | An implementation of [Persistence](./auth.persistence.md#persistence_interface) of SESSION using sessionStorage for the underlying storage. | -| [cordovaPopupRedirectResolver](./auth.md#cordovapopupredirectresolver) | An implementation of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) suitable for Cordova based applications. | | [debugErrorMap](./auth.md#debugerrormap) | A verbose error map with detailed descriptions for most error codes.See discussion at [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) | | [FactorId](./auth.md#factorid) | An enum of factors that may be used for multifactor authentication. | | [indexedDBLocalPersistence](./auth.md#indexeddblocalpersistence) | An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type LOCAL using indexedDB for the underlying storage. | @@ -152,7 +144,6 @@ Firebase Authentication | [OperationType](./auth.md#operationtype) | Enumeration of supported operation types. | | [prodErrorMap](./auth.md#proderrormap) | A minimal error map with all verbose error messages stripped.See discussion at [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) | | [ProviderId](./auth.md#providerid) | Enumeration of supported providers. | -| [reactNativeLocalPersistence](./auth.md#reactnativelocalpersistence) | An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type 'LOCAL' for use in React Native environments. | | [SignInMethod](./auth.md#signinmethod) | Enumeration of supported sign-in methods. | ## Type Aliases @@ -164,79 +155,6 @@ Firebase Authentication | [PhoneInfoOptions](./auth.md#phoneinfooptions) | The information required to verify the ownership of a phone number. | | [UserProfile](./auth.md#userprofile) | User profile used in [AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface). | -## getAuth() - -Returns the Auth instance associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). If no instance exists, initializes an Auth instance with platform-specific default dependencies. - -Signature: - -```typescript -export declare function getAuth(app?: FirebaseApp): Auth; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The Firebase App. | - -Returns: - -[Auth](./auth.auth.md#auth_interface) - -## initializeAuth() - -Initializes an [Auth](./auth.auth.md#auth_interface) instance with fine-grained control over [Dependencies](./auth.dependencies.md#dependencies_interface). - -This function allows more control over the [Auth](./auth.auth.md#auth_interface) instance than [getAuth()](./auth.md#getauth). `getAuth` uses platform-specific defaults to supply the [Dependencies](./auth.dependencies.md#dependencies_interface). In general, `getAuth` is the easiest way to initialize Auth and works for most use cases. Use `initializeAuth` if you need control over which persistence layer is used, or to minimize bundle size if you're not using either `signInWithPopup` or `signInWithRedirect`. - -For example, if your app only uses anonymous accounts and you only want accounts saved for the current session, initialize `Auth` with: - -```js -const auth = initializeAuth(app, { - persistence: browserSessionPersistence, - popupRedirectResolver: undefined, -}); - -``` - -Signature: - -```typescript -export declare function initializeAuth(app: FirebaseApp, deps?: Dependencies): Auth; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | | -| deps | [Dependencies](./auth.dependencies.md#dependencies_interface) | | - -Returns: - -[Auth](./auth.auth.md#auth_interface) - -## getReactNativePersistence() - -Returns a persistence object that wraps `AsyncStorage` imported from `react-native` or `@react-native-community/async-storage`, and can be used in the persistence dependency field in [initializeAuth()](./auth.md#initializeauth). - -Signature: - -```typescript -export declare function getReactNativePersistence(storage: ReactNativeAsyncStorage): Persistence; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| storage | [ReactNativeAsyncStorage](./auth.reactnativeasyncstorage.md#reactnativeasyncstorage_interface) | | - -Returns: - -[Persistence](./auth.persistence.md#persistence_interface) - ## applyActionCode() Applies a verification code sent to the user by email or other out-of-band mechanism. @@ -387,6 +305,28 @@ export declare function createUserWithEmailAndPassword(auth: Auth, email: string Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> +## deleteUser() + +Deletes and signs out the user. + +Important: this is a security-sensitive operation that requires the user to have recently signed in. If this requirement isn't met, ask the user to authenticate again and then call [reauthenticateWithCredential()](./auth.md#reauthenticatewithcredential). + +Signature: + +```typescript +export declare function deleteUser(user: User): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | + +Returns: + +Promise<void> + ## fetchSignInMethodsForEmail() Gets the list of possible sign in methods for the given email address. @@ -410,6 +350,92 @@ export declare function fetchSignInMethodsForEmail(auth: Auth, email: string): P Promise<string\[\]> +## getAdditionalUserInfo() + +Extracts provider specific [AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface) for the given credential. + +Signature: + +```typescript +export declare function getAdditionalUserInfo(userCredential: UserCredential): AdditionalUserInfo | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | + +Returns: + +[AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface) \| null + +## getAuth() + +Returns the Auth instance associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). If no instance exists, initializes an Auth instance with platform-specific default dependencies. + +Signature: + +```typescript +export declare function getAuth(app?: FirebaseApp): Auth; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The Firebase App. | + +Returns: + +[Auth](./auth.auth.md#auth_interface) + +## getIdToken() + +Returns a JSON Web Token (JWT) used to identify the user to a Firebase service. + +Returns the current token if it has not expired or if it will not expire in the next five minutes. Otherwise, this will refresh the token and return a new one. + +Signature: + +```typescript +export declare function getIdToken(user: User, forceRefresh?: boolean): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| forceRefresh | boolean | Force refresh regardless of token expiration. | + +Returns: + +Promise<string> + +## getIdTokenResult() + +Returns a deserialized JSON Web Token (JWT) used to identitfy the user to a Firebase service. + +Returns the current token if it has not expired or if it will not expire in the next five minutes. Otherwise, this will refresh the token and return a new one. + +Signature: + +```typescript +export declare function getIdTokenResult(user: User, forceRefresh?: boolean): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| forceRefresh | boolean | Force refresh regardless of token expiration. | + +Returns: + +Promise<[IdTokenResult](./auth.idtokenresult.md#idtokenresult_interface)> + ## getMultiFactorResolver() Provides a [MultiFactorResolver](./auth.multifactorresolver.md#multifactorresolver_interface) suitable for completion of a multi-factor flow. @@ -482,37 +508,47 @@ const operationType = result.operationType; ``` -## isSignInWithEmailLink() +## initializeAuth() -Checks if an incoming link is a sign-in with email link suitable for [signInWithEmailLink()](./auth.md#signinwithemaillink). +Initializes an [Auth](./auth.auth.md#auth_interface) instance with fine-grained control over [Dependencies](./auth.dependencies.md#dependencies_interface). + +This function allows more control over the [Auth](./auth.auth.md#auth_interface) instance than [getAuth()](./auth.md#getauth). `getAuth` uses platform-specific defaults to supply the [Dependencies](./auth.dependencies.md#dependencies_interface). In general, `getAuth` is the easiest way to initialize Auth and works for most use cases. Use `initializeAuth` if you need control over which persistence layer is used, or to minimize bundle size if you're not using either `signInWithPopup` or `signInWithRedirect`. + +For example, if your app only uses anonymous accounts and you only want accounts saved for the current session, initialize `Auth` with: + +```js +const auth = initializeAuth(app, { + persistence: browserSessionPersistence, + popupRedirectResolver: undefined, +}); + +``` Signature: ```typescript -export declare function isSignInWithEmailLink(auth: Auth, emailLink: string): boolean; +export declare function initializeAuth(app: FirebaseApp, deps?: Dependencies): Auth; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| emailLink | string | The link sent to the user's email address. | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | | +| deps | [Dependencies](./auth.dependencies.md#dependencies_interface) | | Returns: -boolean - -## onAuthStateChanged() +[Auth](./auth.auth.md#auth_interface) -Adds an observer for changes to the user's sign-in state. +## isSignInWithEmailLink() -To keep the old behavior, see [onIdTokenChanged()](./auth.md#onidtokenchanged). +Checks if an incoming link is a sign-in with email link suitable for [signInWithEmailLink()](./auth.md#signinwithemaillink). Signature: ```typescript -export declare function onAuthStateChanged(auth: Auth, nextOrObserver: NextOrObserver, error?: ErrorFn, completed?: CompleteFn): Unsubscribe; +export declare function isSignInWithEmailLink(auth: Auth, emailLink: string): boolean; ``` ### Parameters @@ -520,200 +556,163 @@ export declare function onAuthStateChanged(auth: Auth, nextOrObserver: NextOrObs | Parameter | Type | Description | | --- | --- | --- | | auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| nextOrObserver | [NextOrObserver](./auth.md#nextorobserver)<[User](./auth.user.md#user_interface)> | callback triggered on change. | -| error | [ErrorFn](./util.md#errorfn) | Deprecated. This callback is never triggered. Errors on signing in/out can be caught in promises returned from sign-in/sign-out functions. | -| completed | [CompleteFn](./util.md#completefn) | Deprecated. This callback is never triggered. | +| emailLink | string | The link sent to the user's email address. | Returns: -[Unsubscribe](./util.md#unsubscribe) +boolean -## onIdTokenChanged() +## linkWithCredential() -Adds an observer for changes to the signed-in user's ID token. +Links the user account with the given credentials. -This includes sign-in, sign-out, and token refresh events. +An [AuthProvider](./auth.authprovider.md#authprovider_interface) can be used to generate the credential. Signature: ```typescript -export declare function onIdTokenChanged(auth: Auth, nextOrObserver: NextOrObserver, error?: ErrorFn, completed?: CompleteFn): Unsubscribe; +export declare function linkWithCredential(user: User, credential: AuthCredential): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| nextOrObserver | [NextOrObserver](./auth.md#nextorobserver)<[User](./auth.user.md#user_interface)> | callback triggered on change. | -| error | [ErrorFn](./util.md#errorfn) | Deprecated. This callback is never triggered. Errors on signing in/out can be caught in promises returned from sign-in/sign-out functions. | -| completed | [CompleteFn](./util.md#completefn) | Deprecated. This callback is never triggered. | +| user | [User](./auth.user.md#user_interface) | The user. | +| credential | [AuthCredential](./auth.authcredential.md#authcredential_class) | The auth credential. | Returns: -[Unsubscribe](./util.md#unsubscribe) - -## sendPasswordResetEmail() +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> -Sends a password reset email to the given email address. +## linkWithPhoneNumber() -To complete the password reset, call [confirmPasswordReset()](./auth.md#confirmpasswordreset) with the code supplied in the email sent to the user, along with the new password specified by the user. +Links the user account with the given phone number. Signature: ```typescript -export declare function sendPasswordResetEmail(auth: Auth, email: string, actionCodeSettings?: ActionCodeSettings): Promise; +export declare function linkWithPhoneNumber(user: User, phoneNumber: string, appVerifier: ApplicationVerifier): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| email | string | The user's email address. | -| actionCodeSettings | [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface) | The [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface). | +| user | [User](./auth.user.md#user_interface) | The user. | +| phoneNumber | string | The user's phone number in E.164 format (e.g. +16505550101). | +| appVerifier | [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) | The [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface). | Returns: -Promise<void> - -### Example - - -```javascript -const actionCodeSettings = { - url: 'https://www.example.com/?email=user@example.com', - iOS: { - bundleId: 'com.example.ios' - }, - android: { - packageName: 'com.example.android', - installApp: true, - minimumVersion: '12' - }, - handleCodeInApp: true -}; -await sendPasswordResetEmail(auth, 'user@example.com', actionCodeSettings); -// Obtain code from user. -await confirmPasswordReset('user@example.com', code); - -``` - -## sendSignInLinkToEmail() +Promise<[ConfirmationResult](./auth.confirmationresult.md#confirmationresult_interface)> -Sends a sign-in email link to the user with the specified email. +## linkWithPopup() -The sign-in operation has to always be completed in the app unlike other out of band email actions (password reset and email verifications). This is because, at the end of the flow, the user is expected to be signed in and their Auth state persisted within the app. +Links the authenticated provider to the user account using a pop-up based OAuth flow. -To complete sign in with the email link, call [signInWithEmailLink()](./auth.md#signinwithemaillink) with the email address and the email link supplied in the email sent to the user. +If the linking is successful, the returned result will contain the user and the provider's credential. Signature: ```typescript -export declare function sendSignInLinkToEmail(auth: Auth, email: string, actionCodeSettings: ActionCodeSettings): Promise; +export declare function linkWithPopup(user: User, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | | -| email | string | The user's email address. | -| actionCodeSettings | [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface) | The [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface). | +| user | [User](./auth.user.md#user_interface) | The user. | +| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | +| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | Returns: -Promise<void> +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> ### Example ```javascript -const actionCodeSettings = { - url: 'https://www.example.com/?email=user@example.com', - iOS: { - bundleId: 'com.example.ios' - }, - android: { - packageName: 'com.example.android', - installApp: true, - minimumVersion: '12' - }, - handleCodeInApp: true -}; -await sendSignInLinkToEmail(auth, 'user@example.com', actionCodeSettings); -// Obtain emailLink from the user. -if(isSignInWithEmailLink(auth, emailLink)) { - await signInWithEmailLink(auth, 'user@example.com', emailLink); -} +// Sign in using some other provider. +const result = await signInWithEmailAndPassword(auth, email, password); +// Link using a popup. +const provider = new FacebookAuthProvider(); +await linkWithPopup(result.user, provider); ``` -## setPersistence() - -Changes the type of persistence on the [Auth](./auth.auth.md#auth_interface) instance for the currently saved `Auth` session and applies this type of persistence for future sign-in requests, including sign-in with redirect requests. +## linkWithRedirect() -This makes it easy for a user signing in to specify whether their session should be remembered or not. It also makes it easier to never persist the `Auth` state for applications that are shared by other users or have sensitive data. +Links the [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) to the user account using a full-page redirect flow. Signature: ```typescript -export declare function setPersistence(auth: Auth, persistence: Persistence): Promise; +export declare function linkWithRedirect(user: User, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| persistence | [Persistence](./auth.persistence.md#persistence_interface) | The [Persistence](./auth.persistence.md#persistence_interface) to use. | +| user | [User](./auth.user.md#user_interface) | The user. | +| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | +| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | Returns: -Promise<void> - -A `Promise` that resolves once the persistence change has completed +Promise<never> ### Example ```javascript -setPersistence(auth, browserSessionPersistence); +// Sign in using some other provider. +const result = await signInWithEmailAndPassword(auth, email, password); +// Link using a redirect. +const provider = new FacebookAuthProvider(); +await linkWithRedirect(result.user, provider); +// This will trigger a full page redirect away from your app + +// After returning from the redirect when your app initializes you can obtain the result +const result = await getRedirectResult(auth); ``` -## signInAnonymously() +## multiFactor() -Asynchronously signs in as an anonymous user. +The [MultiFactorUser](./auth.multifactoruser.md#multifactoruser_interface) corresponding to the user. -If there is already an anonymous user signed in, that user will be returned; otherwise, a new anonymous user identity will be created and returned. +This is used to access all multi-factor properties and operations related to the user. Signature: ```typescript -export declare function signInAnonymously(auth: Auth): Promise; +export declare function multiFactor(user: User): MultiFactorUser; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| user | [User](./auth.user.md#user_interface) | The user. | Returns: -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> +[MultiFactorUser](./auth.multifactoruser.md#multifactoruser_interface) -## signInWithCredential() +## onAuthStateChanged() -Asynchronously signs in with the given credentials. +Adds an observer for changes to the user's sign-in state. -An [AuthProvider](./auth.authprovider.md#authprovider_interface) can be used to generate the credential. +To keep the old behavior, see [onIdTokenChanged()](./auth.md#onidtokenchanged). Signature: ```typescript -export declare function signInWithCredential(auth: Auth, credential: AuthCredential): Promise; +export declare function onAuthStateChanged(auth: Auth, nextOrObserver: NextOrObserver, error?: ErrorFn, completed?: CompleteFn): Unsubscribe; ``` ### Parameters @@ -721,24 +720,24 @@ export declare function signInWithCredential(auth: Auth, credential: AuthCredent | Parameter | Type | Description | | --- | --- | --- | | auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| credential | [AuthCredential](./auth.authcredential.md#authcredential_class) | The auth credential. | +| nextOrObserver | [NextOrObserver](./auth.md#nextorobserver)<[User](./auth.user.md#user_interface)> | callback triggered on change. | +| error | [ErrorFn](./util.md#errorfn) | Deprecated. This callback is never triggered. Errors on signing in/out can be caught in promises returned from sign-in/sign-out functions. | +| completed | [CompleteFn](./util.md#completefn) | Deprecated. This callback is never triggered. | Returns: -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -## signInWithCustomToken() +[Unsubscribe](./util.md#unsubscribe) -Asynchronously signs in using a custom token. +## onIdTokenChanged() -Custom tokens are used to integrate Firebase Auth with existing auth systems, and must be generated by an auth backend using the [createCustomToken](https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#createcustomtoken) method in the [Admin SDK](https://firebase.google.com/docs/auth/admin) . +Adds an observer for changes to the signed-in user's ID token. -Fails with an error if the token is invalid, expired, or not accepted by the Firebase Auth service. +This includes sign-in, sign-out, and token refresh events. Signature: ```typescript -export declare function signInWithCustomToken(auth: Auth, customToken: string): Promise; +export declare function onIdTokenChanged(auth: Auth, nextOrObserver: NextOrObserver, error?: ErrorFn, completed?: CompleteFn): Unsubscribe; ``` ### Parameters @@ -746,109 +745,74 @@ export declare function signInWithCustomToken(auth: Auth, customToken: string): | Parameter | Type | Description | | --- | --- | --- | | auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| customToken | string | The custom token to sign in with. | +| nextOrObserver | [NextOrObserver](./auth.md#nextorobserver)<[User](./auth.user.md#user_interface)> | callback triggered on change. | +| error | [ErrorFn](./util.md#errorfn) | Deprecated. This callback is never triggered. Errors on signing in/out can be caught in promises returned from sign-in/sign-out functions. | +| completed | [CompleteFn](./util.md#completefn) | Deprecated. This callback is never triggered. | Returns: -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -## signInWithEmailAndPassword() - -Asynchronously signs in using an email and password. +[Unsubscribe](./util.md#unsubscribe) -Fails with an error if the email address and password do not match. +## parseActionCodeURL() -Note: The user's password is NOT the password used to access the user's email account. The email address serves as a unique identifier for the user, and the password is used to access the user's account in your Firebase project. See also: [createUserWithEmailAndPassword()](./auth.md#createuserwithemailandpassword). +Parses the email action link string and returns an [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) if the link is valid, otherwise returns null. Signature: ```typescript -export declare function signInWithEmailAndPassword(auth: Auth, email: string, password: string): Promise; +export declare function parseActionCodeURL(link: string): ActionCodeURL | null; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| email | string | The users email address. | -| password | string | The users password. | +| link | string | | Returns: -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -## signInWithEmailLink() - -Asynchronously signs in using an email and sign-in email link. +[ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) \| null -If no link is passed, the link is inferred from the current URL. +## reauthenticateWithCredential() -Fails with an error if the email address is invalid or OTP in email link expires. +Re-authenticates a user using a fresh credential. -Note: Confirm the link is a sign-in email link before calling this method firebase.auth.Auth.isSignInWithEmailLink. +Use before operations such as [updatePassword()](./auth.md#updatepassword) that require tokens from recent sign-in attempts. This method can be used to recover from a `CREDENTIAL_TOO_OLD_LOGIN_AGAIN` error. Signature: ```typescript -export declare function signInWithEmailLink(auth: Auth, email: string, emailLink?: string): Promise; +export declare function reauthenticateWithCredential(user: User, credential: AuthCredential): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| email | string | The user's email address. | -| emailLink | string | The link sent to the user's email address. | +| user | [User](./auth.user.md#user_interface) | The user. | +| credential | [AuthCredential](./auth.authcredential.md#authcredential_class) | The auth credential. | Returns: Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> -### Example - - -```javascript -const actionCodeSettings = { - url: 'https://www.example.com/?email=user@example.com', - iOS: { - bundleId: 'com.example.ios' - }, - android: { - packageName: 'com.example.android', - installApp: true, - minimumVersion: '12' - }, - handleCodeInApp: true -}; -await sendSignInLinkToEmail(auth, 'user@example.com', actionCodeSettings); -// Obtain emailLink from the user. -if(isSignInWithEmailLink(auth, emailLink)) { - await signInWithEmailLink(auth, 'user@example.com', emailLink); -} - -``` - -## signInWithPhoneNumber() - -Asynchronously signs in using a phone number. +## reauthenticateWithPhoneNumber() -This method sends a code via SMS to the given phone number, and returns a [ConfirmationResult](./auth.confirmationresult.md#confirmationresult_interface). After the user provides the code sent to their phone, call [ConfirmationResult.confirm()](./auth.confirmationresult.md#confirmationresultconfirm) with the code to sign the user in. +Re-authenticates a user using a fresh phone credential. -For abuse prevention, this method also requires a [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface). This SDK includes a reCAPTCHA-based implementation, [RecaptchaVerifier](./auth.recaptchaverifier.md#recaptchaverifier_class). This function can work on other platforms that do not support the [RecaptchaVerifier](./auth.recaptchaverifier.md#recaptchaverifier_class) (like React Native), but you need to use a third-party [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) implementation. +Use before operations such as [updatePassword()](./auth.md#updatepassword) that require tokens from recent sign-in attempts. Signature: ```typescript -export declare function signInWithPhoneNumber(auth: Auth, phoneNumber: string, appVerifier: ApplicationVerifier): Promise; +export declare function reauthenticateWithPhoneNumber(user: User, phoneNumber: string, appVerifier: ApplicationVerifier): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| user | [User](./auth.user.md#user_interface) | The user. | | phoneNumber | string | The user's phone number in E.164 format (e.g. +16505550101). | | appVerifier | [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) | The [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface). | @@ -856,35 +820,23 @@ export declare function signInWithPhoneNumber(auth: Auth, phoneNumber: string, a Promise<[ConfirmationResult](./auth.confirmationresult.md#confirmationresult_interface)> -### Example - - -```javascript -// 'recaptcha-container' is the ID of an element in the DOM. -const applicationVerifier = new firebase.auth.RecaptchaVerifier('recaptcha-container'); -const confirmationResult = await signInWithPhoneNumber(auth, phoneNumber, applicationVerifier); -// Obtain a verificationCode from the user. -const credential = await confirmationResult.confirm(verificationCode); - -``` - -## signInWithPopup() +## reauthenticateWithPopup() -Authenticates a Firebase client using a popup-based OAuth authentication flow. +Reauthenticates the current user with the specified [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) using a pop-up based OAuth flow. -If succeeds, returns the signed in user along with the provider's credential. If sign in was unsuccessful, returns an error object containing additional information about the error. +If the reauthentication is successful, the returned result will contain the user and the provider's credential. Signature: ```typescript -export declare function signInWithPopup(auth: Auth, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; +export declare function reauthenticateWithPopup(user: User, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| user | [User](./auth.user.md#user_interface) | The user. | | provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | | resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | @@ -899,32 +851,26 @@ Promise<[UserCredential](./auth.usercredential.md#usercredential_interface). Follow the [best practices](https://firebase.google.com/docs/auth/web/redirect-best-practices) when using [signInWithRedirect()](./auth.md#signinwithredirect). +Reauthenticates the current user with the specified [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) using a full-page redirect flow. Signature: ```typescript -export declare function signInWithRedirect(auth: Auth, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; +export declare function reauthenticateWithRedirect(user: User, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| user | [User](./auth.user.md#user_interface) | The user. | | provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | | resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | @@ -938,103 +884,95 @@ Promise<never> ```javascript // Sign in using a redirect. const provider = new FacebookAuthProvider(); -// You can add additional scopes to the provider: -provider.addScope('user_birthday'); -// Start a sign in process for an unauthenticated user. -await signInWithRedirect(auth, provider); +const result = await signInWithRedirect(auth, provider); // This will trigger a full page redirect away from your app // After returning from the redirect when your app initializes you can obtain the result const result = await getRedirectResult(auth); -if (result) { - // This is the signed-in user - const user = result.user; - // This gives you a Facebook Access Token. - const credential = provider.credentialFromResult(auth, result); - const token = credential.accessToken; -} -// As this API can be used for sign-in, linking and reauthentication, -// check the operationType to determine what triggered this redirect -// operation. -const operationType = result.operationType; +// Link using a redirect. +await linkWithRedirect(result.user, provider); +// This will again trigger a full page redirect away from your app + +// After returning from the redirect when your app initializes you can obtain the result +const result = await getRedirectResult(auth); ``` -## signOut() +## reload() -Signs out the current user. +Reloads user account data, if signed in. Signature: ```typescript -export declare function signOut(auth: Auth): Promise; +export declare function reload(user: User): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| user | [User](./auth.user.md#user_interface) | The user. | Returns: Promise<void> -## updateCurrentUser() - -Asynchronously sets the provided user as [Auth.currentUser](./auth.auth.md#authcurrentuser) on the [Auth](./auth.auth.md#auth_interface) instance. - -A new instance copy of the user provided will be made and set as currentUser. +## sendEmailVerification() -This will trigger [onAuthStateChanged()](./auth.md#onauthstatechanged) and [onIdTokenChanged()](./auth.md#onidtokenchanged) listeners like other sign in methods. +Sends a verification email to a user. -The operation fails with an error if the user to be updated belongs to a different Firebase project. +The verification process is completed by calling [applyActionCode()](./auth.md#applyactioncode). Signature: ```typescript -export declare function updateCurrentUser(auth: Auth, user: User | null): Promise; +export declare function sendEmailVerification(user: User, actionCodeSettings?: ActionCodeSettings | null): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| user | [User](./auth.user.md#user_interface) \| null | The new [User](./auth.user.md#user_interface). | +| user | [User](./auth.user.md#user_interface) | The user. | +| actionCodeSettings | [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface) \| null | The [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface). | Returns: Promise<void> -## useDeviceLanguage() +### Example -Sets the current language to the default device/browser preference. -Signature: +```javascript +const actionCodeSettings = { + url: 'https://www.example.com/?email=user@example.com', + iOS: { + bundleId: 'com.example.ios' + }, + android: { + packageName: 'com.example.android', + installApp: true, + minimumVersion: '12' + }, + handleCodeInApp: true +}; +await sendEmailVerification(user, actionCodeSettings); +// Obtain code from the user. +await applyActionCode(auth, code); -```typescript -export declare function useDeviceLanguage(auth: Auth): void; ``` -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | - -Returns: - -void +## sendPasswordResetEmail() -## verifyPasswordResetCode() +Sends a password reset email to the given email address. -Checks a password reset code sent to the user by email or other out-of-band mechanism. +To complete the password reset, call [confirmPasswordReset()](./auth.md#confirmpasswordreset) with the code supplied in the email sent to the user, along with the new password specified by the user. Signature: ```typescript -export declare function verifyPasswordResetCode(auth: Auth, code: string): Promise; +export declare function sendPasswordResetEmail(auth: Auth, email: string, actionCodeSettings?: ActionCodeSettings): Promise; ``` ### Parameters @@ -1042,285 +980,285 @@ export declare function verifyPasswordResetCode(auth: Auth, code: string): Promi | Parameter | Type | Description | | --- | --- | --- | | auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| code | string | A verification code sent to the user. | +| email | string | The user's email address. | +| actionCodeSettings | [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface) | The [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface). | Returns: -Promise<string> - -the user's email address if valid. +Promise<void> -## parseActionCodeURL() +### Example -Parses the email action link string and returns an [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) if the link is valid, otherwise returns null. -Signature: +```javascript +const actionCodeSettings = { + url: 'https://www.example.com/?email=user@example.com', + iOS: { + bundleId: 'com.example.ios' + }, + android: { + packageName: 'com.example.android', + installApp: true, + minimumVersion: '12' + }, + handleCodeInApp: true +}; +await sendPasswordResetEmail(auth, 'user@example.com', actionCodeSettings); +// Obtain code from user. +await confirmPasswordReset('user@example.com', code); -```typescript -export declare function parseActionCodeURL(link: string): ActionCodeURL | null; ``` -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| link | string | | - -Returns: - -[ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) \| null +## sendSignInLinkToEmail() -## deleteUser() +Sends a sign-in email link to the user with the specified email. -Deletes and signs out the user. +The sign-in operation has to always be completed in the app unlike other out of band email actions (password reset and email verifications). This is because, at the end of the flow, the user is expected to be signed in and their Auth state persisted within the app. -Important: this is a security-sensitive operation that requires the user to have recently signed in. If this requirement isn't met, ask the user to authenticate again and then call [reauthenticateWithCredential()](./auth.md#reauthenticatewithcredential). +To complete sign in with the email link, call [signInWithEmailLink()](./auth.md#signinwithemaillink) with the email address and the email link supplied in the email sent to the user. Signature: ```typescript -export declare function deleteUser(user: User): Promise; +export declare function sendSignInLinkToEmail(auth: Auth, email: string, actionCodeSettings: ActionCodeSettings): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | +| auth | [Auth](./auth.auth.md#auth_interface) | | +| email | string | The user's email address. | +| actionCodeSettings | [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface) | The [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface). | Returns: Promise<void> -## getIdToken() - -Returns a JSON Web Token (JWT) used to identify the user to a Firebase service. +### Example -Returns the current token if it has not expired or if it will not expire in the next five minutes. Otherwise, this will refresh the token and return a new one. -Signature: +```javascript +const actionCodeSettings = { + url: 'https://www.example.com/?email=user@example.com', + iOS: { + bundleId: 'com.example.ios' + }, + android: { + packageName: 'com.example.android', + installApp: true, + minimumVersion: '12' + }, + handleCodeInApp: true +}; +await sendSignInLinkToEmail(auth, 'user@example.com', actionCodeSettings); +// Obtain emailLink from the user. +if(isSignInWithEmailLink(auth, emailLink)) { + await signInWithEmailLink(auth, 'user@example.com', emailLink); +} -```typescript -export declare function getIdToken(user: User, forceRefresh?: boolean): Promise; ``` -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| forceRefresh | boolean | Force refresh regardless of token expiration. | - -Returns: - -Promise<string> - -## getIdTokenResult() +## setPersistence() -Returns a deserialized JSON Web Token (JWT) used to identitfy the user to a Firebase service. +Changes the type of persistence on the [Auth](./auth.auth.md#auth_interface) instance for the currently saved `Auth` session and applies this type of persistence for future sign-in requests, including sign-in with redirect requests. -Returns the current token if it has not expired or if it will not expire in the next five minutes. Otherwise, this will refresh the token and return a new one. +This makes it easy for a user signing in to specify whether their session should be remembered or not. It also makes it easier to never persist the `Auth` state for applications that are shared by other users or have sensitive data. Signature: ```typescript -export declare function getIdTokenResult(user: User, forceRefresh?: boolean): Promise; +export declare function setPersistence(auth: Auth, persistence: Persistence): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| forceRefresh | boolean | Force refresh regardless of token expiration. | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| persistence | [Persistence](./auth.persistence.md#persistence_interface) | The [Persistence](./auth.persistence.md#persistence_interface) to use. | Returns: -Promise<[IdTokenResult](./auth.idtokenresult.md#idtokenresult_interface)> +Promise<void> -## linkWithCredential() +A `Promise` that resolves once the persistence change has completed -Links the user account with the given credentials. +### Example -An [AuthProvider](./auth.authprovider.md#authprovider_interface) can be used to generate the credential. -Signature: +```javascript +setPersistence(auth, browserSessionPersistence); -```typescript -export declare function linkWithCredential(user: User, credential: AuthCredential): Promise; ``` -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| credential | [AuthCredential](./auth.authcredential.md#authcredential_class) | The auth credential. | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> +## signInAnonymously() -## linkWithPhoneNumber() +Asynchronously signs in as an anonymous user. -Links the user account with the given phone number. +If there is already an anonymous user signed in, that user will be returned; otherwise, a new anonymous user identity will be created and returned. Signature: ```typescript -export declare function linkWithPhoneNumber(user: User, phoneNumber: string, appVerifier: ApplicationVerifier): Promise; +export declare function signInAnonymously(auth: Auth): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| phoneNumber | string | The user's phone number in E.164 format (e.g. +16505550101). | -| appVerifier | [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) | The [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface). | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | Returns: -Promise<[ConfirmationResult](./auth.confirmationresult.md#confirmationresult_interface)> +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> -## linkWithPopup() +## signInWithCredential() -Links the authenticated provider to the user account using a pop-up based OAuth flow. +Asynchronously signs in with the given credentials. -If the linking is successful, the returned result will contain the user and the provider's credential. +An [AuthProvider](./auth.authprovider.md#authprovider_interface) can be used to generate the credential. Signature: ```typescript -export declare function linkWithPopup(user: User, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; +export declare function signInWithCredential(auth: Auth, credential: AuthCredential): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | -| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| credential | [AuthCredential](./auth.authcredential.md#authcredential_class) | The auth credential. | Returns: Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> -### Example - - -```javascript -// Sign in using some other provider. -const result = await signInWithEmailAndPassword(auth, email, password); -// Link using a popup. -const provider = new FacebookAuthProvider(); -await linkWithPopup(result.user, provider); - -``` +## signInWithCustomToken() -## linkWithRedirect() +Asynchronously signs in using a custom token. -Links the [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) to the user account using a full-page redirect flow. +Custom tokens are used to integrate Firebase Auth with existing auth systems, and must be generated by an auth backend using the [createCustomToken](https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#createcustomtoken) method in the [Admin SDK](https://firebase.google.com/docs/auth/admin) . -To handle the results and errors for this operation, refer to [getRedirectResult()](./auth.md#getredirectresult). Follow the [best practices](https://firebase.google.com/docs/auth/web/redirect-best-practices) when using [linkWithRedirect()](./auth.md#linkwithredirect). +Fails with an error if the token is invalid, expired, or not accepted by the Firebase Auth service. Signature: ```typescript -export declare function linkWithRedirect(user: User, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; +export declare function signInWithCustomToken(auth: Auth, customToken: string): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | -| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| customToken | string | The custom token to sign in with. | Returns: -Promise<never> - -### Example - - -```javascript -// Sign in using some other provider. -const result = await signInWithEmailAndPassword(auth, email, password); -// Link using a redirect. -const provider = new FacebookAuthProvider(); -await linkWithRedirect(result.user, provider); -// This will trigger a full page redirect away from your app - -// After returning from the redirect when your app initializes you can obtain the result -const result = await getRedirectResult(auth); +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> -``` +## signInWithEmailAndPassword() -## multiFactor() +Asynchronously signs in using an email and password. -The [MultiFactorUser](./auth.multifactoruser.md#multifactoruser_interface) corresponding to the user. +Fails with an error if the email address and password do not match. -This is used to access all multi-factor properties and operations related to the user. +Note: The user's password is NOT the password used to access the user's email account. The email address serves as a unique identifier for the user, and the password is used to access the user's account in your Firebase project. See also: [createUserWithEmailAndPassword()](./auth.md#createuserwithemailandpassword). Signature: ```typescript -export declare function multiFactor(user: User): MultiFactorUser; +export declare function signInWithEmailAndPassword(auth: Auth, email: string, password: string): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| email | string | The users email address. | +| password | string | The users password. | Returns: -[MultiFactorUser](./auth.multifactoruser.md#multifactoruser_interface) +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> -## reauthenticateWithCredential() +## signInWithEmailLink() -Re-authenticates a user using a fresh credential. +Asynchronously signs in using an email and sign-in email link. + +If no link is passed, the link is inferred from the current URL. + +Fails with an error if the email address is invalid or OTP in email link expires. -Use before operations such as [updatePassword()](./auth.md#updatepassword) that require tokens from recent sign-in attempts. This method can be used to recover from a `CREDENTIAL_TOO_OLD_LOGIN_AGAIN` error or a `TOKEN_EXPIRED` error. +Note: Confirm the link is a sign-in email link before calling this method firebase.auth.Auth.isSignInWithEmailLink. Signature: ```typescript -export declare function reauthenticateWithCredential(user: User, credential: AuthCredential): Promise; +export declare function signInWithEmailLink(auth: Auth, email: string, emailLink?: string): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| credential | [AuthCredential](./auth.authcredential.md#authcredential_class) | The auth credential. | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| email | string | The user's email address. | +| emailLink | string | The link sent to the user's email address. | Returns: Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> -## reauthenticateWithPhoneNumber() +### Example -Re-authenticates a user using a fresh phone credential. -Use before operations such as [updatePassword()](./auth.md#updatepassword) that require tokens from recent sign-in attempts. +```javascript +const actionCodeSettings = { + url: 'https://www.example.com/?email=user@example.com', + iOS: { + bundleId: 'com.example.ios' + }, + android: { + packageName: 'com.example.android', + installApp: true, + minimumVersion: '12' + }, + handleCodeInApp: true +}; +await sendSignInLinkToEmail(auth, 'user@example.com', actionCodeSettings); +// Obtain emailLink from the user. +if(isSignInWithEmailLink(auth, emailLink)) { + await signInWithEmailLink(auth, 'user@example.com', emailLink); +} + +``` + +## signInWithPhoneNumber() + +Asynchronously signs in using a phone number. + +This method sends a code via SMS to the given phone number, and returns a [ConfirmationResult](./auth.confirmationresult.md#confirmationresult_interface). After the user provides the code sent to their phone, call [ConfirmationResult.confirm()](./auth.confirmationresult.md#confirmationresultconfirm) with the code to sign the user in. + +For abuse prevention, this method also requires a [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface). This SDK includes a reCAPTCHA-based implementation, [RecaptchaVerifier](./auth.recaptchaverifier.md#recaptchaverifier_class). This function can work on other platforms that do not support the [RecaptchaVerifier](./auth.recaptchaverifier.md#recaptchaverifier_class) (like React Native), but you need to use a third-party [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) implementation. Signature: ```typescript -export declare function reauthenticateWithPhoneNumber(user: User, phoneNumber: string, appVerifier: ApplicationVerifier): Promise; +export declare function signInWithPhoneNumber(auth: Auth, phoneNumber: string, appVerifier: ApplicationVerifier): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | | phoneNumber | string | The user's phone number in E.164 format (e.g. +16505550101). | | appVerifier | [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) | The [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface). | @@ -1328,23 +1266,35 @@ export declare function reauthenticateWithPhoneNumber(user: User, phoneNumber: s Promise<[ConfirmationResult](./auth.confirmationresult.md#confirmationresult_interface)> -## reauthenticateWithPopup() +### Example -Reauthenticates the current user with the specified [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) using a pop-up based OAuth flow. -If the reauthentication is successful, the returned result will contain the user and the provider's credential. +```javascript +// 'recaptcha-container' is the ID of an element in the DOM. +const applicationVerifier = new firebase.auth.RecaptchaVerifier('recaptcha-container'); +const confirmationResult = await signInWithPhoneNumber(auth, phoneNumber, applicationVerifier); +// Obtain a verificationCode from the user. +const credential = await confirmationResult.confirm(verificationCode); + +``` + +## signInWithPopup() + +Authenticates a Firebase client using a popup-based OAuth authentication flow. + +If succeeds, returns the signed in user along with the provider's credential. If sign in was unsuccessful, returns an error object containing additional information about the error. Signature: ```typescript -export declare function reauthenticateWithPopup(user: User, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; +export declare function signInWithPopup(auth: Auth, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | | provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | | resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | @@ -1359,28 +1309,32 @@ Promise<[UserCredential](./auth.usercredential.md#usercredential_interface). Follow the [best practices](https://firebase.google.com/docs/auth/web/redirect-best-practices) when using [reauthenticateWithRedirect()](./auth.md#reauthenticatewithredirect). +To handle the results and errors for this operation, refer to [getRedirectResult()](./auth.md#getredirectresult). Signature: ```typescript -export declare function reauthenticateWithRedirect(user: User, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; +export declare function signInWithRedirect(auth: Auth, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | | provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | | resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | @@ -1394,50 +1348,56 @@ Promise<never> ```javascript // Sign in using a redirect. const provider = new FacebookAuthProvider(); -const result = await signInWithRedirect(auth, provider); +// You can add additional scopes to the provider: +provider.addScope('user_birthday'); +// Start a sign in process for an unauthenticated user. +await signInWithRedirect(auth, provider); // This will trigger a full page redirect away from your app // After returning from the redirect when your app initializes you can obtain the result const result = await getRedirectResult(auth); -// Reauthenticate using a redirect. -await reauthenticateWithRedirect(result.user, provider); -// This will again trigger a full page redirect away from your app - -// After returning from the redirect when your app initializes you can obtain the result -const result = await getRedirectResult(auth); +if (result) { + // This is the signed-in user + const user = result.user; + // This gives you a Facebook Access Token. + const credential = provider.credentialFromResult(auth, result); + const token = credential.accessToken; +} +// As this API can be used for sign-in, linking and reauthentication, +// check the operationType to determine what triggered this redirect +// operation. +const operationType = result.operationType; ``` -## reload() +## signOut() -Reloads user account data, if signed in. +Signs out the current user. Signature: ```typescript -export declare function reload(user: User): Promise; +export declare function signOut(auth: Auth): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | Returns: Promise<void> -## sendEmailVerification() - -Sends a verification email to a user. +## unlink() -The verification process is completed by calling [applyActionCode()](./auth.md#applyactioncode). +Unlinks a provider from a user account. Signature: ```typescript -export declare function sendEmailVerification(user: User, actionCodeSettings?: ActionCodeSettings | null): Promise; +export declare function unlink(user: User, providerId: string): Promise; ``` ### Parameters @@ -1445,54 +1405,38 @@ export declare function sendEmailVerification(user: User, actionCodeSettings?: A | Parameter | Type | Description | | --- | --- | --- | | user | [User](./auth.user.md#user_interface) | The user. | -| actionCodeSettings | [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface) \| null | The [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface). | +| providerId | string | The provider to unlink. | Returns: -Promise<void> - -### Example +Promise<[User](./auth.user.md#user_interface)> +## updateCurrentUser() -```javascript -const actionCodeSettings = { - url: 'https://www.example.com/?email=user@example.com', - iOS: { - bundleId: 'com.example.ios' - }, - android: { - packageName: 'com.example.android', - installApp: true, - minimumVersion: '12' - }, - handleCodeInApp: true -}; -await sendEmailVerification(user, actionCodeSettings); -// Obtain code from the user. -await applyActionCode(auth, code); +Asynchronously sets the provided user as [Auth.currentUser](./auth.auth.md#authcurrentuser) on the [Auth](./auth.auth.md#auth_interface) instance. -``` +A new instance copy of the user provided will be made and set as currentUser. -## unlink() +This will trigger [onAuthStateChanged()](./auth.md#onauthstatechanged) and [onIdTokenChanged()](./auth.md#onidtokenchanged) listeners like other sign in methods. -Unlinks a provider from a user account. +The operation fails with an error if the user to be updated belongs to a different Firebase project. Signature: ```typescript -export declare function unlink(user: User, providerId: string): Promise; +export declare function updateCurrentUser(auth: Auth, user: User | null): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| providerId | string | The provider to unlink. | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| user | [User](./auth.user.md#user_interface) \| null | The new [User](./auth.user.md#user_interface). | Returns: -Promise<[User](./auth.user.md#user_interface)> +Promise<void> ## updateEmail() @@ -1601,6 +1545,26 @@ export declare function updateProfile(user: User, { displayName, photoURL: photo Promise<void> +## useDeviceLanguage() + +Sets the current language to the default device/browser preference. + +Signature: + +```typescript +export declare function useDeviceLanguage(auth: Auth): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | + +Returns: + +void + ## verifyBeforeUpdateEmail() Sends a verification email to a new email address. @@ -1649,25 +1613,28 @@ await applyActionCode(auth, code); ``` -## getAdditionalUserInfo() +## verifyPasswordResetCode() -Extracts provider specific [AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface) for the given credential. +Checks a password reset code sent to the user by email or other out-of-band mechanism. Signature: ```typescript -export declare function getAdditionalUserInfo(userCredential: UserCredential): AdditionalUserInfo | null; +export declare function verifyPasswordResetCode(auth: Auth, code: string): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| code | string | A verification code sent to the user. | Returns: -[AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface) \| null +Promise<string> + +the user's email address if valid. ## ActionCodeOperation @@ -1824,16 +1791,6 @@ An implementation of [Persistence](./auth.persistence.md#persistence_interface) browserSessionPersistence: Persistence ``` -## cordovaPopupRedirectResolver - -An implementation of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) suitable for Cordova based applications. - -Signature: - -```typescript -cordovaPopupRedirectResolver: PopupRedirectResolver -``` - ## debugErrorMap A verbose error map with detailed descriptions for most error codes. @@ -1921,16 +1878,6 @@ ProviderId: { } ``` -## reactNativeLocalPersistence - -An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type 'LOCAL' for use in React Native environments. - -Signature: - -```typescript -reactNativeLocalPersistence: Persistence -``` - ## SignInMethod Enumeration of supported sign-in methods. diff --git a/docs-devsite/database.md b/docs-devsite/database.md index 686ca7f8580..114c364858a 100644 --- a/docs-devsite/database.md +++ b/docs-devsite/database.md @@ -16,37 +16,22 @@ Firebase Realtime Database | Function | Description | | --- | --- | -| function(app...) | -| [getDatabase(app, url)](./database.md#getdatabase) | Returns the instance of the Realtime Database SDK that is associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). Initializes a new instance with with default settings if no instance exists or if the existing instance uses a custom database URL. | -| function(db...) | +| [child(parent, path)](./database.md#child) | Gets a Reference for the location at the specified relative path.The relative path can either be a simple child name (for example, "ada") or a deeper slash-separated path (for example, "ada/name/first"). | | [connectDatabaseEmulator(db, host, port, options)](./database.md#connectdatabaseemulator) | Modify the provided instance to communicate with the Realtime Database emulator.

Note: This method must be called before performing any other operation. | -| [goOffline(db)](./database.md#gooffline) | Disconnects from the server (all Database operations will be completed offline).The client automatically maintains a persistent connection to the Database server, which will remain active indefinitely and reconnect when disconnected. However, the goOffline() and goOnline() methods may be used to control the client connection in cases where a persistent connection is undesirable.While offline, the client will no longer receive data updates from the Database. However, all Database operations performed locally will continue to immediately fire events, allowing your application to continue behaving normally. Additionally, each operation performed locally will automatically be queued and retried upon reconnection to the Database server.To reconnect to the Database and begin receiving remote events, see goOnline(). | -| [goOnline(db)](./database.md#goonline) | Reconnects to the server and synchronizes the offline Database state with the server state.This method should be used after disabling the active connection with goOffline(). Once reconnected, the client will transmit the proper data and fire the appropriate events so that your client "catches up" automatically. | -| [ref(db, path)](./database.md#ref) | Returns a Reference representing the location in the Database corresponding to the provided path. If no path is provided, the Reference will point to the root of the Database. | -| [refFromURL(db, url)](./database.md#reffromurl) | Returns a Reference representing the location in the Database corresponding to the provided Firebase URL.An exception is thrown if the URL is not a valid Firebase Database URL or it has a different domain than the current Database instance.Note that all query parameters (orderBy, limitToLast, etc.) are ignored and are not applied to the returned Reference. | -| function() | +| [enableLogging(enabled, persistent)](./database.md#enablelogging) | Logs debugging information to the console. | +| [enableLogging(logger)](./database.md#enablelogging) | Logs debugging information to the console. | +| [endAt(value, key)](./database.md#endat) | Creates a QueryConstraint with the specified ending point.Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The ending point is inclusive, so children with exactly the specified value will be included in the query. The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have a key name less than or equal to the specified key.You can read more about endAt() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | +| [endBefore(value, key)](./database.md#endbefore) | Creates a QueryConstraint with the specified ending point (exclusive).Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The ending point is exclusive. If only a value is provided, children with a value less than the specified value will be included in the query. If a key is specified, then children must have a value less than or equal to the specified value and a key name less than the specified key. | +| [equalTo(value, key)](./database.md#equalto) | Creates a QueryConstraint that includes children that match the specified value.Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have exactly the specified key as their key name. This can be used to filter result sets with many matches for the same value.You can read more about equalTo() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | | [forceLongPolling()](./database.md#forcelongpolling) | Force the use of longPolling instead of websockets. This will be ignored if websocket protocol is used in databaseURL. | | [forceWebSockets()](./database.md#forcewebsockets) | Force the use of websockets instead of longPolling. | -| [orderByKey()](./database.md#orderbykey) | Creates a new QueryConstraint that orders by the key.Sorts the results of a query by their (ascending) key values.You can read more about orderByKey() in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). | -| [orderByPriority()](./database.md#orderbypriority) | Creates a new QueryConstraint that orders by priority.Applications need not use priority but can order collections by ordinary properties (see [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data) for alternatives to priority. | -| [orderByValue()](./database.md#orderbyvalue) | Creates a new QueryConstraint that orders by value.If the children of a query are all scalar values (string, number, or boolean), you can order the results by their (ascending) values.You can read more about orderByValue() in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). | -| [serverTimestamp()](./database.md#servertimestamp) | Returns a placeholder value for auto-populating the current timestamp (time since the Unix epoch, in milliseconds) as determined by the Firebase servers. | -| function(delta...) | +| [get(query)](./database.md#get) | Gets the most up-to-date result for this query. | +| [getDatabase(app, url)](./database.md#getdatabase) | Returns the instance of the Realtime Database SDK that is associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). Initializes a new instance with with default settings if no instance exists or if the existing instance uses a custom database URL. | +| [goOffline(db)](./database.md#gooffline) | Disconnects from the server (all Database operations will be completed offline).The client automatically maintains a persistent connection to the Database server, which will remain active indefinitely and reconnect when disconnected. However, the goOffline() and goOnline() methods may be used to control the client connection in cases where a persistent connection is undesirable.While offline, the client will no longer receive data updates from the Database. However, all Database operations performed locally will continue to immediately fire events, allowing your application to continue behaving normally. Additionally, each operation performed locally will automatically be queued and retried upon reconnection to the Database server.To reconnect to the Database and begin receiving remote events, see goOnline(). | +| [goOnline(db)](./database.md#goonline) | Reconnects to the server and synchronizes the offline Database state with the server state.This method should be used after disabling the active connection with goOffline(). Once reconnected, the client will transmit the proper data and fire the appropriate events so that your client "catches up" automatically. | | [increment(delta)](./database.md#increment) | Returns a placeholder value that can be used to atomically increment the current database value by the provided delta. | -| function(enabled...) | -| [enableLogging(enabled, persistent)](./database.md#enablelogging) | Logs debugging information to the console. | -| function(limit...) | | [limitToFirst(limit)](./database.md#limittofirst) | Creates a new QueryConstraint that if limited to the first specific number of children.The limitToFirst() method is used to set a maximum number of children to be synced for a given callback. If we set a limit of 100, we will initially only receive up to 100 child_added events. If we have fewer than 100 messages stored in our Database, a child_added event will fire for each message. However, if we have over 100 messages, we will only receive a child_added event for the first 100 ordered messages. As items change, we will receive child_removed events for each item that drops out of the active list so that the total number stays at 100.You can read more about limitToFirst() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | | [limitToLast(limit)](./database.md#limittolast) | Creates a new QueryConstraint that is limited to return only the last specified number of children.The limitToLast() method is used to set a maximum number of children to be synced for a given callback. If we set a limit of 100, we will initially only receive up to 100 child_added events. If we have fewer than 100 messages stored in our Database, a child_added event will fire for each message. However, if we have over 100 messages, we will only receive a child_added event for the last 100 ordered messages. As items change, we will receive child_removed events for each item that drops out of the active list so that the total number stays at 100.You can read more about limitToLast() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | -| function(logger...) | -| [enableLogging(logger)](./database.md#enablelogging) | Logs debugging information to the console. | -| function(parent...) | -| [child(parent, path)](./database.md#child) | Gets a Reference for the location at the specified relative path.The relative path can either be a simple child name (for example, "ada") or a deeper slash-separated path (for example, "ada/name/first"). | -| [push(parent, value)](./database.md#push) | Generates a new child location using a unique key and returns its Reference.This is the most common pattern for adding data to a collection of items.If you provide a value to push(), the value is written to the generated location. If you don't pass a value, nothing is written to the database and the child remains empty (but you can use the Reference elsewhere).The unique keys generated by push() are ordered by the current time, so the resulting list of items is chronologically sorted. The keys are also designed to be unguessable (they contain 72 random bits of entropy).See [Append to a list of data](https://firebase.google.com/docs/database/web/lists-of-data#append_to_a_list_of_data). See [The 2^120 Ways to Ensure Unique Identifiers](https://firebase.googleblog.com/2015/02/the-2120-ways-to-ensure-unique_68.html). | -| function(path...) | -| [orderByChild(path)](./database.md#orderbychild) | Creates a new QueryConstraint that orders by the specified child key.Queries can only order by one key at a time. Calling orderByChild() multiple times on the same query is an error.Firebase queries allow you to order your data by any child key on the fly. However, if you know in advance what your indexes will be, you can define them via the .indexOn rule in your Security Rules for better performance. See the[https://firebase.google.com/docs/database/security/indexing-data](https://firebase.google.com/docs/database/security/indexing-data) rule for more information.You can read more about orderByChild() in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). | -| function(query...) | -| [get(query)](./database.md#get) | Gets the most up-to-date result for this query. | | [off(query, eventType, callback)](./database.md#off) | Detaches a callback previously attached with the corresponding on*() (onValue, onChildAdded) listener. Note: This is not the recommended way to remove a listener. Instead, please use the returned callback function from the respective on* callbacks.Detach a callback previously attached with on*(). Calling off() on a parent listener will not automatically remove listeners registered on child nodes, off() must also be called on any child listeners to remove the callback.If a callback is not specified, all callbacks for the specified eventType will be removed. Similarly, if no eventType is specified, all callbacks for the Reference will be removed.Individual listeners can also be removed by invoking their unsubscribe callbacks. | | [onChildAdded(query, callback, cancelCallback)](./database.md#onchildadded) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildAdded event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The DataSnapshot passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | | [onChildAdded(query, callback, options)](./database.md#onchildadded) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildAdded event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The DataSnapshot passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | @@ -60,24 +45,27 @@ Firebase Realtime Database | [onChildRemoved(query, callback, cancelCallback)](./database.md#onchildremoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildRemoved event will be triggered once every time a child is removed. The DataSnapshot passed into the callback will be the old data for the child that was removed. A child will get removed when either:- a client explicitly calls remove() on that child or one of its ancestors - a client calls set(null) on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) | | [onChildRemoved(query, callback, options)](./database.md#onchildremoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildRemoved event will be triggered once every time a child is removed. The DataSnapshot passed into the callback will be the old data for the child that was removed. A child will get removed when either:- a client explicitly calls remove() on that child or one of its ancestors - a client calls set(null) on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) | | [onChildRemoved(query, callback, cancelCallback, options)](./database.md#onchildremoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildRemoved event will be triggered once every time a child is removed. The DataSnapshot passed into the callback will be the old data for the child that was removed. A child will get removed when either:- a client explicitly calls remove() on that child or one of its ancestors - a client calls set(null) on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) | +| [onDisconnect(ref)](./database.md#ondisconnect) | Returns an OnDisconnect object - see [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information on how to use it. | | [onValue(query, callback, cancelCallback)](./database.md#onvalue) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onValue event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The DataSnapshot passed to the callback will be for the location at which on() was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty DataSnapshot (val() will return null). | | [onValue(query, callback, options)](./database.md#onvalue) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onValue event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The DataSnapshot passed to the callback will be for the location at which on() was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty DataSnapshot (val() will return null). | | [onValue(query, callback, cancelCallback, options)](./database.md#onvalue) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onValue event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The DataSnapshot passed to the callback will be for the location at which on() was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty DataSnapshot (val() will return null). | +| [orderByChild(path)](./database.md#orderbychild) | Creates a new QueryConstraint that orders by the specified child key.Queries can only order by one key at a time. Calling orderByChild() multiple times on the same query is an error.Firebase queries allow you to order your data by any child key on the fly. However, if you know in advance what your indexes will be, you can define them via the .indexOn rule in your Security Rules for better performance. See the[https://firebase.google.com/docs/database/security/indexing-data](https://firebase.google.com/docs/database/security/indexing-data) rule for more information.You can read more about orderByChild() in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). | +| [orderByKey()](./database.md#orderbykey) | Creates a new QueryConstraint that orders by the key.Sorts the results of a query by their (ascending) key values.You can read more about orderByKey() in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). | +| [orderByPriority()](./database.md#orderbypriority) | Creates a new QueryConstraint that orders by priority.Applications need not use priority but can order collections by ordinary properties (see [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data) for alternatives to priority. | +| [orderByValue()](./database.md#orderbyvalue) | Creates a new QueryConstraint that orders by value.If the children of a query are all scalar values (string, number, or boolean), you can order the results by their (ascending) values.You can read more about orderByValue() in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). | +| [push(parent, value)](./database.md#push) | Generates a new child location using a unique key and returns its Reference.This is the most common pattern for adding data to a collection of items.If you provide a value to push(), the value is written to the generated location. If you don't pass a value, nothing is written to the database and the child remains empty (but you can use the Reference elsewhere).The unique keys generated by push() are ordered by the current time, so the resulting list of items is chronologically sorted. The keys are also designed to be unguessable (they contain 72 random bits of entropy).See [Append to a list of data](https://firebase.google.com/docs/database/web/lists-of-data#append_to_a_list_of_data). See [The 2^120 Ways to Ensure Unique Identifiers](https://firebase.googleblog.com/2015/02/the-2120-ways-to-ensure-unique_68.html). | | [query(query, queryConstraints)](./database.md#query) | Creates a new immutable instance of Query that is extended to also include additional query constraints. | -| function(ref...) | -| [onDisconnect(ref)](./database.md#ondisconnect) | Returns an OnDisconnect object - see [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information on how to use it. | +| [ref(db, path)](./database.md#ref) | Returns a Reference representing the location in the Database corresponding to the provided path. If no path is provided, the Reference will point to the root of the Database. | +| [refFromURL(db, url)](./database.md#reffromurl) | Returns a Reference representing the location in the Database corresponding to the provided Firebase URL.An exception is thrown if the URL is not a valid Firebase Database URL or it has a different domain than the current Database instance.Note that all query parameters (orderBy, limitToLast, etc.) are ignored and are not applied to the returned Reference. | | [remove(ref)](./database.md#remove) | Removes the data at this Database location.Any data at child locations will also be deleted.The effect of the remove will be visible immediately and the corresponding event 'value' will be triggered. Synchronization of the remove to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the onComplete callback will be called asynchronously after synchronization has finished. | | [runTransaction(ref, transactionUpdate, options)](./database.md#runtransaction) | Atomically modifies the data at this location.Atomically modify the data at this location. Unlike a normal set(), which just overwrites the data regardless of its previous value, runTransaction() is used to modify the existing value to a new value, ensuring there are no conflicts with other clients writing to the same location at the same time.To accomplish this, you pass runTransaction() an update function which is used to transform the current value into a new value. If another client writes to the location before your new value is successfully written, your update function will be called again with the new current value, and the write will be retried. This will happen repeatedly until your write succeeds without conflict or you abort the transaction by not returning a value from your update function.Note: Modifying data with set() will cancel any pending transactions at that location, so extreme care should be taken if mixing set() and runTransaction() to update the same data.Note: When using transactions with Security and Firebase Rules in place, be aware that a client needs .read access in addition to .write access in order to perform a transaction. This is because the client-side nature of transactions requires the client to read the data in order to transactionally update it. | +| [serverTimestamp()](./database.md#servertimestamp) | Returns a placeholder value for auto-populating the current timestamp (time since the Unix epoch, in milliseconds) as determined by the Firebase servers. | | [set(ref, value)](./database.md#set) | Writes data to this Database location.This will overwrite any data at this location and all child locations.The effect of the write will be visible immediately, and the corresponding events ("value", "child\_added", etc.) will be triggered. Synchronization of the data to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the onComplete callback will be called asynchronously after synchronization has finished.Passing null for the new value is equivalent to calling remove(); namely, all data at this location and all child locations will be deleted.set() will remove any priority stored at this location, so if priority is meant to be preserved, you need to use setWithPriority() instead.Note that modifying data with set() will cancel any pending transactions at that location, so extreme care should be taken if mixing set() and transaction() to modify the same data.A single set() will generate a single "value" event at the location where the set() was performed. | | [setPriority(ref, priority)](./database.md#setpriority) | Sets a priority for the data at this Database location.Applications need not use priority but can order collections by ordinary properties (see [Sorting and filtering data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) ). | | [setWithPriority(ref, value, priority)](./database.md#setwithpriority) | Writes data the Database location. Like set() but also specifies the priority for that data.Applications need not use priority but can order collections by ordinary properties (see [Sorting and filtering data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) ). | -| [update(ref, values)](./database.md#update) | Writes multiple values to the Database at once.The values argument contains multiple property-value pairs that will be written to the Database together. Each child property can either be a simple property (for example, "name") or a relative path (for example, "name/first") from the current location to the data to update.As opposed to the set() method, update() can be use to selectively update only the referenced properties at the current location (instead of replacing all the child properties at the current location).The effect of the write will be visible immediately, and the corresponding events ('value', 'child\_added', etc.) will be triggered. Synchronization of the data to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the onComplete callback will be called asynchronously after synchronization has finished.A single update() will generate a single "value" event at the location where the update() was performed, regardless of how many children were modified.Note that modifying data with update() will cancel any pending transactions at that location, so extreme care should be taken if mixing update() and transaction() to modify the same data.Passing null to update() will remove the data at this location.See [Introducing multi-location updates and more](https://firebase.googleblog.com/2015/09/introducing-multi-location-updates-and_86.html). | -| function(value...) | -| [endAt(value, key)](./database.md#endat) | Creates a QueryConstraint with the specified ending point.Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The ending point is inclusive, so children with exactly the specified value will be included in the query. The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have a key name less than or equal to the specified key.You can read more about endAt() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | -| [endBefore(value, key)](./database.md#endbefore) | Creates a QueryConstraint with the specified ending point (exclusive).Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The ending point is exclusive. If only a value is provided, children with a value less than the specified value will be included in the query. If a key is specified, then children must have a value less than or equal to the specified value and a key name less than the specified key. | -| [equalTo(value, key)](./database.md#equalto) | Creates a QueryConstraint that includes children that match the specified value.Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have exactly the specified key as their key name. This can be used to filter result sets with many matches for the same value.You can read more about equalTo() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | | [startAfter(value, key)](./database.md#startafter) | Creates a QueryConstraint with the specified starting point (exclusive).Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The starting point is exclusive. If only a value is provided, children with a value greater than the specified value will be included in the query. If a key is specified, then children must have a value greater than or equal to the specified value and a a key name greater than the specified key. | | [startAt(value, key)](./database.md#startat) | Creates a QueryConstraint with the specified starting point.Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The starting point is inclusive, so children with exactly the specified value will be included in the query. The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have a key name greater than or equal to the specified key.You can read more about startAt() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | +| [update(ref, values)](./database.md#update) | Writes multiple values to the Database at once.The values argument contains multiple property-value pairs that will be written to the Database together. Each child property can either be a simple property (for example, "name") or a relative path (for example, "name/first") from the current location to the data to update.As opposed to the set() method, update() can be use to selectively update only the referenced properties at the current location (instead of replacing all the child properties at the current location).The effect of the write will be visible immediately, and the corresponding events ('value', 'child\_added', etc.) will be triggered. Synchronization of the data to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the onComplete callback will be called asynchronously after synchronization has finished.A single update() will generate a single "value" event at the location where the update() was performed, regardless of how many children were modified.Note that modifying data with update() will cancel any pending transactions at that location, so extreme care should be taken if mixing update() and transaction() to modify the same data.Passing null to update() will remove the data at this location.See [Introducing multi-location updates and more](https://firebase.googleblog.com/2015/09/introducing-multi-location-updates-and_86.html). | ## Classes @@ -107,28 +95,30 @@ Firebase Realtime Database | [QueryConstraintType](./database.md#queryconstrainttype) | Describes the different query constraints available in this SDK. | | [Unsubscribe](./database.md#unsubscribe) | A callback that can invoked to remove a listener. | -## getDatabase() +## child() -Returns the instance of the Realtime Database SDK that is associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). Initializes a new instance with with default settings if no instance exists or if the existing instance uses a custom database URL. +Gets a `Reference` for the location at the specified relative path. + +The relative path can either be a simple child name (for example, "ada") or a deeper slash-separated path (for example, "ada/name/first"). Signature: ```typescript -export declare function getDatabase(app?: FirebaseApp, url?: string): Database; +export declare function child(parent: DatabaseReference, path: string): DatabaseReference; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance that the returned Realtime Database instance is associated with. | -| url | string | The URL of the Realtime Database instance to connect to. If not provided, the SDK connects to the default instance of the Firebase App. | +| parent | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The parent location. | +| path | string | A relative path from this location to the desired child location. | Returns: -[Database](./database.database.md#database_class) +[DatabaseReference](./database.databasereference.md#databasereference_interface) -The `Database` instance of the provided app. +The specified child location. ## connectDatabaseEmulator() @@ -157,103 +147,125 @@ export declare function connectDatabaseEmulator(db: Database, host: string, port void -## goOffline() +## enableLogging() -Disconnects from the server (all Database operations will be completed offline). +Logs debugging information to the console. -The client automatically maintains a persistent connection to the Database server, which will remain active indefinitely and reconnect when disconnected. However, the `goOffline()` and `goOnline()` methods may be used to control the client connection in cases where a persistent connection is undesirable. +Signature: -While offline, the client will no longer receive data updates from the Database. However, all Database operations performed locally will continue to immediately fire events, allowing your application to continue behaving normally. Additionally, each operation performed locally will automatically be queued and retried upon reconnection to the Database server. +```typescript +export declare function enableLogging(enabled: boolean, persistent?: boolean): any; +``` -To reconnect to the Database and begin receiving remote events, see `goOnline()`. +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| enabled | boolean | Enables logging if true, disables logging if false. | +| persistent | boolean | Remembers the logging state between page refreshes if true. | + +Returns: + +any + +## enableLogging() + +Logs debugging information to the console. Signature: ```typescript -export declare function goOffline(db: Database): void; +export declare function enableLogging(logger: (message: string) => unknown): any; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| db | [Database](./database.database.md#database_class) | The instance to disconnect. | +| logger | (message: string) => unknown | A custom logger function to control how things get logged. | Returns: -void +any -## goOnline() +## endAt() -Reconnects to the server and synchronizes the offline Database state with the server state. +Creates a `QueryConstraint` with the specified ending point. -This method should be used after disabling the active connection with `goOffline()`. Once reconnected, the client will transmit the proper data and fire the appropriate events so that your client "catches up" automatically. +Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. + +The ending point is inclusive, so children with exactly the specified value will be included in the query. The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have a key name less than or equal to the specified key. + +You can read more about `endAt()` in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). Signature: ```typescript -export declare function goOnline(db: Database): void; +export declare function endAt(value: number | string | boolean | null, key?: string): QueryConstraint; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| db | [Database](./database.database.md#database_class) | The instance to reconnect. | +| value | number \| string \| boolean \| null | The value to end at. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | +| key | string | The child key to end at, among the children with the previously specified priority. This argument is only allowed if ordering by child, value, or priority. | Returns: -void +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) -## ref() +## endBefore() -Returns a `Reference` representing the location in the Database corresponding to the provided path. If no path is provided, the `Reference` will point to the root of the Database. +Creates a `QueryConstraint` with the specified ending point (exclusive). + +Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. + +The ending point is exclusive. If only a value is provided, children with a value less than the specified value will be included in the query. If a key is specified, then children must have a value less than or equal to the specified value and a key name less than the specified key. Signature: ```typescript -export declare function ref(db: Database, path?: string): DatabaseReference; +export declare function endBefore(value: number | string | boolean | null, key?: string): QueryConstraint; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| db | [Database](./database.database.md#database_class) | The database instance to obtain a reference for. | -| path | string | Optional path representing the location the returned Reference will point. If not provided, the returned Reference will point to the root of the Database. | +| value | number \| string \| boolean \| null | The value to end before. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | +| key | string | The child key to end before, among the children with the previously specified priority. This argument is only allowed if ordering by child, value, or priority. | Returns: -[DatabaseReference](./database.databasereference.md#databasereference_interface) +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) -If a path is provided, a `Reference` pointing to the provided path. Otherwise, a `Reference` pointing to the root of the Database. +## equalTo() -## refFromURL() +Creates a `QueryConstraint` that includes children that match the specified value. -Returns a `Reference` representing the location in the Database corresponding to the provided Firebase URL. +Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. -An exception is thrown if the URL is not a valid Firebase Database URL or it has a different domain than the current `Database` instance. +The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have exactly the specified key as their key name. This can be used to filter result sets with many matches for the same value. -Note that all query parameters (`orderBy`, `limitToLast`, etc.) are ignored and are not applied to the returned `Reference`. +You can read more about `equalTo()` in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). Signature: ```typescript -export declare function refFromURL(db: Database, url: string): DatabaseReference; +export declare function equalTo(value: number | string | boolean | null, key?: string): QueryConstraint; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| db | [Database](./database.database.md#database_class) | The database instance to obtain a reference for. | -| url | string | The Firebase URL at which the returned Reference will point. | +| value | number \| string \| boolean \| null | The value to match for. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | +| key | string | The child key to start at, among the children with the previously specified priority. This argument is only allowed if ordering by child, value, or priority. | Returns: -[DatabaseReference](./database.databasereference.md#databasereference_interface) - -A `Reference` pointing to the provided Firebase URL. +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) ## forceLongPolling() @@ -281,110 +293,120 @@ export declare function forceWebSockets(): void; void -## orderByKey() - -Creates a new `QueryConstraint` that orders by the key. - -Sorts the results of a query by their (ascending) key values. +## get() -You can read more about `orderByKey()` in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). +Gets the most up-to-date result for this query. Signature: ```typescript -export declare function orderByKey(): QueryConstraint; +export declare function get(query: Query): Promise; ``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | + Returns: -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) +Promise<[DataSnapshot](./database.datasnapshot.md#datasnapshot_class)> -## orderByPriority() +A `Promise` which resolves to the resulting DataSnapshot if a value is available, or rejects if the client is unable to return a value (e.g., if the server is unreachable and there is nothing cached). -Creates a new `QueryConstraint` that orders by priority. +## getDatabase() -Applications need not use priority but can order collections by ordinary properties (see [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data) for alternatives to priority. +Returns the instance of the Realtime Database SDK that is associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). Initializes a new instance with with default settings if no instance exists or if the existing instance uses a custom database URL. Signature: ```typescript -export declare function orderByPriority(): QueryConstraint; +export declare function getDatabase(app?: FirebaseApp, url?: string): Database; ``` -Returns: -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) +### Parameters -## orderByValue() +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance that the returned Realtime Database instance is associated with. | +| url | string | The URL of the Realtime Database instance to connect to. If not provided, the SDK connects to the default instance of the Firebase App. | -Creates a new `QueryConstraint` that orders by value. +Returns: -If the children of a query are all scalar values (string, number, or boolean), you can order the results by their (ascending) values. +[Database](./database.database.md#database_class) -You can read more about `orderByValue()` in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). +The `Database` instance of the provided app. -Signature: +## goOffline() -```typescript -export declare function orderByValue(): QueryConstraint; -``` -Returns: +Disconnects from the server (all Database operations will be completed offline). -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) +The client automatically maintains a persistent connection to the Database server, which will remain active indefinitely and reconnect when disconnected. However, the `goOffline()` and `goOnline()` methods may be used to control the client connection in cases where a persistent connection is undesirable. -## serverTimestamp() +While offline, the client will no longer receive data updates from the Database. However, all Database operations performed locally will continue to immediately fire events, allowing your application to continue behaving normally. Additionally, each operation performed locally will automatically be queued and retried upon reconnection to the Database server. -Returns a placeholder value for auto-populating the current timestamp (time since the Unix epoch, in milliseconds) as determined by the Firebase servers. +To reconnect to the Database and begin receiving remote events, see `goOnline()`. Signature: ```typescript -export declare function serverTimestamp(): object; +export declare function goOffline(db: Database): void; ``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| db | [Database](./database.database.md#database_class) | The instance to disconnect. | + Returns: -object +void -## increment() +## goOnline() -Returns a placeholder value that can be used to atomically increment the current database value by the provided delta. +Reconnects to the server and synchronizes the offline Database state with the server state. + +This method should be used after disabling the active connection with `goOffline()`. Once reconnected, the client will transmit the proper data and fire the appropriate events so that your client "catches up" automatically. Signature: ```typescript -export declare function increment(delta: number): object; +export declare function goOnline(db: Database): void; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| delta | number | the amount to modify the current value atomically. | +| db | [Database](./database.database.md#database_class) | The instance to reconnect. | Returns: -object - -A placeholder value for modifying data atomically server-side. +void -## enableLogging() +## increment() -Logs debugging information to the console. +Returns a placeholder value that can be used to atomically increment the current database value by the provided delta. Signature: ```typescript -export declare function enableLogging(enabled: boolean, persistent?: boolean): any; +export declare function increment(delta: number): object; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| enabled | boolean | Enables logging if true, disables logging if false. | -| persistent | boolean | Remembers the logging state between page refreshes if true. | +| delta | number | the amount to modify the current value atomically. | Returns: -any +object + +A placeholder value for modifying data atomically server-side. ## limitToFirst() @@ -434,163 +456,39 @@ export declare function limitToLast(limit: number): QueryConstraint; [QueryConstraint](./database.queryconstraint.md#queryconstraint_class) -## enableLogging() +## off() -Logs debugging information to the console. +Detaches a callback previously attached with the corresponding `on*()` (`onValue`, `onChildAdded`) listener. Note: This is not the recommended way to remove a listener. Instead, please use the returned callback function from the respective `on*` callbacks. + +Detach a callback previously attached with `on*()`. Calling `off()` on a parent listener will not automatically remove listeners registered on child nodes, `off()` must also be called on any child listeners to remove the callback. + +If a callback is not specified, all callbacks for the specified eventType will be removed. Similarly, if no eventType is specified, all callbacks for the `Reference` will be removed. + +Individual listeners can also be removed by invoking their unsubscribe callbacks. Signature: ```typescript -export declare function enableLogging(logger: (message: string) => unknown): any; +export declare function off(query: Query, eventType?: EventType, callback?: (snapshot: DataSnapshot, previousChildName?: string | null) => unknown): void; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| logger | (message: string) => unknown | A custom logger function to control how things get logged. | +| query | [Query](./database.query.md#query_interface) | The query that the listener was registered with. | +| eventType | [EventType](./database.md#eventtype) | One of the following strings: "value", "child\_added", "child\_changed", "child\_removed", or "child\_moved." If omitted, all callbacks for the Reference will be removed. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName?: string \| null) => unknown | The callback function that was passed to on() or undefined to remove all callbacks. | Returns: -any +void -## child() +## onChildAdded() -Gets a `Reference` for the location at the specified relative path. +Listens for data changes at a particular location. -The relative path can either be a simple child name (for example, "ada") or a deeper slash-separated path (for example, "ada/name/first"). - -Signature: - -```typescript -export declare function child(parent: DatabaseReference, path: string): DatabaseReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| parent | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The parent location. | -| path | string | A relative path from this location to the desired child location. | - -Returns: - -[DatabaseReference](./database.databasereference.md#databasereference_interface) - -The specified child location. - -## push() - -Generates a new child location using a unique key and returns its `Reference`. - -This is the most common pattern for adding data to a collection of items. - -If you provide a value to `push()`, the value is written to the generated location. If you don't pass a value, nothing is written to the database and the child remains empty (but you can use the `Reference` elsewhere). - -The unique keys generated by `push()` are ordered by the current time, so the resulting list of items is chronologically sorted. The keys are also designed to be unguessable (they contain 72 random bits of entropy). - -See [Append to a list of data](https://firebase.google.com/docs/database/web/lists-of-data#append_to_a_list_of_data). See [The 2^120 Ways to Ensure Unique Identifiers](https://firebase.googleblog.com/2015/02/the-2120-ways-to-ensure-unique_68.html). - -Signature: - -```typescript -export declare function push(parent: DatabaseReference, value?: unknown): ThenableReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| parent | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The parent location. | -| value | unknown | Optional value to be written at the generated location. | - -Returns: - -[ThenableReference](./database.thenablereference.md#thenablereference_interface) - -Combined `Promise` and `Reference`; resolves when write is complete, but can be used immediately as the `Reference` to the child location. - -## orderByChild() - -Creates a new `QueryConstraint` that orders by the specified child key. - -Queries can only order by one key at a time. Calling `orderByChild()` multiple times on the same query is an error. - -Firebase queries allow you to order your data by any child key on the fly. However, if you know in advance what your indexes will be, you can define them via the .indexOn rule in your Security Rules for better performance. See the[https://firebase.google.com/docs/database/security/indexing-data](https://firebase.google.com/docs/database/security/indexing-data) rule for more information. - -You can read more about `orderByChild()` in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). - -Signature: - -```typescript -export declare function orderByChild(path: string): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| path | string | The path to order by. | - -Returns: - -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) - -## get() - -Gets the most up-to-date result for this query. - -Signature: - -```typescript -export declare function get(query: Query): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | - -Returns: - -Promise<[DataSnapshot](./database.datasnapshot.md#datasnapshot_class)> - -A `Promise` which resolves to the resulting DataSnapshot if a value is available, or rejects if the client is unable to return a value (e.g., if the server is unreachable and there is nothing cached). - -## off() - -Detaches a callback previously attached with the corresponding `on*()` (`onValue`, `onChildAdded`) listener. Note: This is not the recommended way to remove a listener. Instead, please use the returned callback function from the respective `on*` callbacks. - -Detach a callback previously attached with `on*()`. Calling `off()` on a parent listener will not automatically remove listeners registered on child nodes, `off()` must also be called on any child listeners to remove the callback. - -If a callback is not specified, all callbacks for the specified eventType will be removed. Similarly, if no eventType is specified, all callbacks for the `Reference` will be removed. - -Individual listeners can also be removed by invoking their unsubscribe callbacks. - -Signature: - -```typescript -export declare function off(query: Query, eventType?: EventType, callback?: (snapshot: DataSnapshot, previousChildName?: string | null) => unknown): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query that the listener was registered with. | -| eventType | [EventType](./database.md#eventtype) | One of the following strings: "value", "child\_added", "child\_changed", "child\_removed", or "child\_moved." If omitted, all callbacks for the Reference will be removed. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName?: string \| null) => unknown | The callback function that was passed to on() or undefined to remove all callbacks. | - -Returns: - -void - -## onChildAdded() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. An `onChildAdded` event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The `DataSnapshot` passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. @@ -932,6 +830,26 @@ export declare function onChildRemoved(query: Query, callback: (snapshot: DataSn A function that can be invoked to remove the listener. +## onDisconnect() + +Returns an `OnDisconnect` object - see [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information on how to use it. + +Signature: + +```typescript +export declare function onDisconnect(ref: DatabaseReference): OnDisconnect; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The reference to add OnDisconnect triggers for. | + +Returns: + +[OnDisconnect](./database.ondisconnect.md#ondisconnect_class) + ## onValue() Listens for data changes at a particular location. @@ -1017,6 +935,112 @@ export declare function onValue(query: Query, callback: (snapshot: DataSnapshot) A function that can be invoked to remove the listener. +## orderByChild() + +Creates a new `QueryConstraint` that orders by the specified child key. + +Queries can only order by one key at a time. Calling `orderByChild()` multiple times on the same query is an error. + +Firebase queries allow you to order your data by any child key on the fly. However, if you know in advance what your indexes will be, you can define them via the .indexOn rule in your Security Rules for better performance. See the[https://firebase.google.com/docs/database/security/indexing-data](https://firebase.google.com/docs/database/security/indexing-data) rule for more information. + +You can read more about `orderByChild()` in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). + +Signature: + +```typescript +export declare function orderByChild(path: string): QueryConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| path | string | The path to order by. | + +Returns: + +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) + +## orderByKey() + +Creates a new `QueryConstraint` that orders by the key. + +Sorts the results of a query by their (ascending) key values. + +You can read more about `orderByKey()` in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). + +Signature: + +```typescript +export declare function orderByKey(): QueryConstraint; +``` +Returns: + +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) + +## orderByPriority() + +Creates a new `QueryConstraint` that orders by priority. + +Applications need not use priority but can order collections by ordinary properties (see [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data) for alternatives to priority. + +Signature: + +```typescript +export declare function orderByPriority(): QueryConstraint; +``` +Returns: + +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) + +## orderByValue() + +Creates a new `QueryConstraint` that orders by value. + +If the children of a query are all scalar values (string, number, or boolean), you can order the results by their (ascending) values. + +You can read more about `orderByValue()` in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). + +Signature: + +```typescript +export declare function orderByValue(): QueryConstraint; +``` +Returns: + +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) + +## push() + +Generates a new child location using a unique key and returns its `Reference`. + +This is the most common pattern for adding data to a collection of items. + +If you provide a value to `push()`, the value is written to the generated location. If you don't pass a value, nothing is written to the database and the child remains empty (but you can use the `Reference` elsewhere). + +The unique keys generated by `push()` are ordered by the current time, so the resulting list of items is chronologically sorted. The keys are also designed to be unguessable (they contain 72 random bits of entropy). + +See [Append to a list of data](https://firebase.google.com/docs/database/web/lists-of-data#append_to_a_list_of_data). See [The 2^120 Ways to Ensure Unique Identifiers](https://firebase.googleblog.com/2015/02/the-2120-ways-to-ensure-unique_68.html). + +Signature: + +```typescript +export declare function push(parent: DatabaseReference, value?: unknown): ThenableReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| parent | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The parent location. | +| value | unknown | Optional value to be written at the generated location. | + +Returns: + +[ThenableReference](./database.thenablereference.md#thenablereference_interface) + +Combined `Promise` and `Reference`; resolves when write is complete, but can be used immediately as the `Reference` to the child location. + ## query() Creates a new immutable instance of `Query` that is extended to also include additional query constraints. @@ -1042,25 +1066,55 @@ export declare function query(query: Query, ...queryConstraints: QueryConstraint if any of the provided query constraints cannot be combined with the existing or new constraints. -## onDisconnect() +## ref() -Returns an `OnDisconnect` object - see [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information on how to use it. +Returns a `Reference` representing the location in the Database corresponding to the provided path. If no path is provided, the `Reference` will point to the root of the Database. Signature: ```typescript -export declare function onDisconnect(ref: DatabaseReference): OnDisconnect; +export declare function ref(db: Database, path?: string): DatabaseReference; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The reference to add OnDisconnect triggers for. | +| db | [Database](./database.database.md#database_class) | The database instance to obtain a reference for. | +| path | string | Optional path representing the location the returned Reference will point. If not provided, the returned Reference will point to the root of the Database. | Returns: -[OnDisconnect](./database.ondisconnect.md#ondisconnect_class) +[DatabaseReference](./database.databasereference.md#databasereference_interface) + +If a path is provided, a `Reference` pointing to the provided path. Otherwise, a `Reference` pointing to the root of the Database. + +## refFromURL() + +Returns a `Reference` representing the location in the Database corresponding to the provided Firebase URL. + +An exception is thrown if the URL is not a valid Firebase Database URL or it has a different domain than the current `Database` instance. + +Note that all query parameters (`orderBy`, `limitToLast`, etc.) are ignored and are not applied to the returned `Reference`. + +Signature: + +```typescript +export declare function refFromURL(db: Database, url: string): DatabaseReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| db | [Database](./database.database.md#database_class) | The database instance to obtain a reference for. | +| url | string | The Firebase URL at which the returned Reference will point. | + +Returns: + +[DatabaseReference](./database.databasereference.md#databasereference_interface) + +A `Reference` pointing to the provided Firebase URL. ## remove() @@ -1120,6 +1174,19 @@ Promise<[TransactionResult](./database.transactionresult.md#transactionresult A `Promise` that can optionally be used instead of the `onComplete` callback to handle success and failure. +## serverTimestamp() + +Returns a placeholder value for auto-populating the current timestamp (time since the Unix epoch, in milliseconds) as determined by the Firebase servers. + +Signature: + +```typescript +export declare function serverTimestamp(): object; +``` +Returns: + +object + ## set() Writes data to this Database location. @@ -1206,173 +1273,94 @@ Promise<void> Resolves when write to server is complete. -## update() - -Writes multiple values to the Database at once. - -The `values` argument contains multiple property-value pairs that will be written to the Database together. Each child property can either be a simple property (for example, "name") or a relative path (for example, "name/first") from the current location to the data to update. - -As opposed to the `set()` method, `update()` can be use to selectively update only the referenced properties at the current location (instead of replacing all the child properties at the current location). - -The effect of the write will be visible immediately, and the corresponding events ('value', 'child\_added', etc.) will be triggered. Synchronization of the data to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the `onComplete` callback will be called asynchronously after synchronization has finished. - -A single `update()` will generate a single "value" event at the location where the `update()` was performed, regardless of how many children were modified. - -Note that modifying data with `update()` will cancel any pending transactions at that location, so extreme care should be taken if mixing `update()` and `transaction()` to modify the same data. - -Passing `null` to `update()` will remove the data at this location. - -See [Introducing multi-location updates and more](https://firebase.googleblog.com/2015/09/introducing-multi-location-updates-and_86.html). - -Signature: - -```typescript -export declare function update(ref: DatabaseReference, values: object): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location to write to. | -| values | object | Object containing multiple values. | - -Returns: - -Promise<void> - -Resolves when update on server is complete. - -## endAt() - -Creates a `QueryConstraint` with the specified ending point. - -Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. - -The ending point is inclusive, so children with exactly the specified value will be included in the query. The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have a key name less than or equal to the specified key. - -You can read more about `endAt()` in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). - -Signature: - -```typescript -export declare function endAt(value: number | string | boolean | null, key?: string): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| value | number \| string \| boolean \| null | The value to end at. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | -| key | string | The child key to end at, among the children with the previously specified priority. This argument is only allowed if ordering by child, value, or priority. | - -Returns: - -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) - -## endBefore() +## startAfter() -Creates a `QueryConstraint` with the specified ending point (exclusive). +Creates a `QueryConstraint` with the specified starting point (exclusive). Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. -The ending point is exclusive. If only a value is provided, children with a value less than the specified value will be included in the query. If a key is specified, then children must have a value less than or equal to the specified value and a key name less than the specified key. +The starting point is exclusive. If only a value is provided, children with a value greater than the specified value will be included in the query. If a key is specified, then children must have a value greater than or equal to the specified value and a a key name greater than the specified key. Signature: ```typescript -export declare function endBefore(value: number | string | boolean | null, key?: string): QueryConstraint; +export declare function startAfter(value: number | string | boolean | null, key?: string): QueryConstraint; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| value | number \| string \| boolean \| null | The value to end before. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | -| key | string | The child key to end before, among the children with the previously specified priority. This argument is only allowed if ordering by child, value, or priority. | +| value | number \| string \| boolean \| null | The value to start after. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | +| key | string | The child key to start after. This argument is only allowed if ordering by child, value, or priority. | Returns: [QueryConstraint](./database.queryconstraint.md#queryconstraint_class) -## equalTo() +## startAt() -Creates a `QueryConstraint` that includes children that match the specified value. +Creates a `QueryConstraint` with the specified starting point. Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. -The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have exactly the specified key as their key name. This can be used to filter result sets with many matches for the same value. +The starting point is inclusive, so children with exactly the specified value will be included in the query. The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have a key name greater than or equal to the specified key. -You can read more about `equalTo()` in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). +You can read more about `startAt()` in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). Signature: ```typescript -export declare function equalTo(value: number | string | boolean | null, key?: string): QueryConstraint; +export declare function startAt(value?: number | string | boolean | null, key?: string): QueryConstraint; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| value | number \| string \| boolean \| null | The value to match for. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | -| key | string | The child key to start at, among the children with the previously specified priority. This argument is only allowed if ordering by child, value, or priority. | +| value | number \| string \| boolean \| null | The value to start at. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | +| key | string | The child key to start at. This argument is only allowed if ordering by child, value, or priority. | Returns: [QueryConstraint](./database.queryconstraint.md#queryconstraint_class) -## startAfter() - -Creates a `QueryConstraint` with the specified starting point (exclusive). - -Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. - -The starting point is exclusive. If only a value is provided, children with a value greater than the specified value will be included in the query. If a key is specified, then children must have a value greater than or equal to the specified value and a a key name greater than the specified key. - -Signature: - -```typescript -export declare function startAfter(value: number | string | boolean | null, key?: string): QueryConstraint; -``` - -### Parameters +## update() -| Parameter | Type | Description | -| --- | --- | --- | -| value | number \| string \| boolean \| null | The value to start after. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | -| key | string | The child key to start after. This argument is only allowed if ordering by child, value, or priority. | +Writes multiple values to the Database at once. -Returns: +The `values` argument contains multiple property-value pairs that will be written to the Database together. Each child property can either be a simple property (for example, "name") or a relative path (for example, "name/first") from the current location to the data to update. -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) +As opposed to the `set()` method, `update()` can be use to selectively update only the referenced properties at the current location (instead of replacing all the child properties at the current location). -## startAt() +The effect of the write will be visible immediately, and the corresponding events ('value', 'child\_added', etc.) will be triggered. Synchronization of the data to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the `onComplete` callback will be called asynchronously after synchronization has finished. -Creates a `QueryConstraint` with the specified starting point. +A single `update()` will generate a single "value" event at the location where the `update()` was performed, regardless of how many children were modified. -Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. +Note that modifying data with `update()` will cancel any pending transactions at that location, so extreme care should be taken if mixing `update()` and `transaction()` to modify the same data. -The starting point is inclusive, so children with exactly the specified value will be included in the query. The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have a key name greater than or equal to the specified key. +Passing `null` to `update()` will remove the data at this location. -You can read more about `startAt()` in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). +See [Introducing multi-location updates and more](https://firebase.googleblog.com/2015/09/introducing-multi-location-updates-and_86.html). Signature: ```typescript -export declare function startAt(value?: number | string | boolean | null, key?: string): QueryConstraint; +export declare function update(ref: DatabaseReference, values: object): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| value | number \| string \| boolean \| null | The value to start at. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | -| key | string | The child key to start at. This argument is only allowed if ordering by child, value, or priority. | +| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location to write to. | +| values | object | Object containing multiple values. | Returns: -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) +Promise<void> + +Resolves when update on server is complete. ## EventType diff --git a/docs-devsite/firestore_.md b/docs-devsite/firestore_.md index 4a5c2dd49b2..7fcf1b9426e 100644 --- a/docs-devsite/firestore_.md +++ b/docs-devsite/firestore_.md @@ -15,90 +15,77 @@ https://github.com/firebase/firebase-js-sdk | Function | Description | | --- | --- | -| 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. | -| [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...) | +| [addDoc(reference, data)](./firestore_.md#adddoc) | Add a new document to specified CollectionReference with the given data, assigning it a document ID automatically. | +| [aggregateQuerySnapshotEqual(left, right)](./firestore_.md#aggregatequerysnapshotequal) | Compares two AggregateQuerySnapshot instances for equality.Two AggregateQuerySnapshot instances are considered "equal" if they have underlying queries that compare equal, and the same data. | +| [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. | | [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. | | [collection(firestore, path, pathSegments)](./firestore_.md#collection) | Gets a CollectionReference instance that refers to the collection at the specified absolute path. | +| [collection(reference, path, pathSegments)](./firestore_.md#collection) | Gets a CollectionReference instance that refers to a subcollection of reference at the the specified relative path. | +| [collection(reference, path, pathSegments)](./firestore_.md#collection) | Gets a CollectionReference instance that refers to a subcollection of reference at the the specified relative path. | | [collectionGroup(firestore, collectionId)](./firestore_.md#collectiongroup) | Creates and returns a new Query instance that includes all documents in the database that are contained in a collection or subcollection with the given collectionId. | | [connectFirestoreEmulator(firestore, host, port, options)](./firestore_.md#connectfirestoreemulator) | Modify this instance to communicate with the Cloud Firestore emulator.Note: This must be called before this instance has been used to do any operations. | +| [deleteDoc(reference)](./firestore_.md#deletedoc) | Deletes the document referred to by the specified DocumentReference. | +| [deleteField()](./firestore_.md#deletefield) | Returns a sentinel for use with [updateDoc()](./firestore_lite.md#updatedoc) or [setDoc()](./firestore_lite.md#setdoc) with {merge: true} to mark a field for deletion. | | [disableNetwork(firestore)](./firestore_.md#disablenetwork) | Disables network usage for this instance. It can be re-enabled via [enableNetwork()](./firestore_.md#enablenetwork). While the network is disabled, any snapshot listeners, getDoc() or getDocs() calls will return results from cache, and any write operations will be queued until the network is restored. | | [doc(firestore, path, pathSegments)](./firestore_.md#doc) | Gets a DocumentReference instance that refers to the document at the specified absolute path. | +| [doc(reference, path, pathSegments)](./firestore_.md#doc) | Gets a DocumentReference instance that refers to a document within reference at the specified relative path. If no path is specified, an automatically-generated unique ID will be used for the returned DocumentReference. | +| [doc(reference, path, pathSegments)](./firestore_.md#doc) | Gets a DocumentReference instance that refers to a document within reference at the specified relative path. | +| [documentId()](./firestore_.md#documentid) | Returns a special sentinel FieldPath to refer to the ID of a document. It can be used in queries to sort or filter by the document ID. | | [enableIndexedDbPersistence(firestore, persistenceSettings)](./firestore_.md#enableindexeddbpersistence) | Attempts to enable persistent storage, if possible.Must be called before any other functions (other than [initializeFirestore()](./firestore_.md#initializefirestore), [getFirestore()](./firestore_.md#getfirestore) or [clearIndexedDbPersistence()](./firestore_.md#clearindexeddbpersistence).If this fails, enableIndexedDbPersistence() will reject the promise it returns. Note that even after this failure, the [Firestore](./firestore_.firestore.md#firestore_class) instance will remain usable, however offline persistence will be disabled.There are several reasons why this can fail, which can be identified by the code on the error.\* failed-precondition: The app is already open in another browser tab. \* unimplemented: The browser is incompatible with the offline persistence implementation. | | [enableMultiTabIndexedDbPersistence(firestore)](./firestore_.md#enablemultitabindexeddbpersistence) | Attempts to enable multi-tab persistent storage, if possible. If enabled across all tabs, all operations share access to local persistence, including shared execution of queries and latency-compensated local document updates across all connected instances.If this fails, enableMultiTabIndexedDbPersistence() will reject the promise it returns. Note that even after this failure, the [Firestore](./firestore_.firestore.md#firestore_class) instance will remain usable, however offline persistence will be disabled.There are several reasons why this can fail, which can be identified by the code on the error.\* failed-precondition: The app is already open in another browser tab and multi-tab is not enabled. \* unimplemented: The browser is incompatible with the offline persistence implementation. | | [enableNetwork(firestore)](./firestore_.md#enablenetwork) | Re-enables use of the network for this [Firestore](./firestore_.firestore.md#firestore_class) instance after a prior call to [disableNetwork()](./firestore_.md#disablenetwork). | -| [loadBundle(firestore, bundleData)](./firestore_.md#loadbundle) | Loads a Firestore bundle into the local cache. | -| [namedQuery(firestore, name)](./firestore_.md#namedquery) | Reads a Firestore [Query](./firestore_.query.md#query_class) 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](./firestore_.query.md#query_class) by name. | -| [onSnapshotsInSync(firestore, observer)](./firestore_.md#onsnapshotsinsync) | Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners.NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use SnapshotMetadata in the individual listeners to determine if a snapshot is from the cache or the server. | -| [onSnapshotsInSync(firestore, onSync)](./firestore_.md#onsnapshotsinsync) | Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners.NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use SnapshotMetadata in the individual listeners to determine if a snapshot is from the cache or the server. | -| [runTransaction(firestore, updateFunction, options)](./firestore_.md#runtransaction) | Executes the given updateFunction and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, Cloud Firestore retries the updateFunction. If it fails to commit after 5 attempts, the transaction fails.The maximum number of writes allowed in a single transaction is 500. | -| [setIndexConfiguration(firestore, configuration)](./firestore_.md#setindexconfiguration) | (BETA) Configures indexing for local query execution. Any previous index configuration is overridden. The Promise resolves once the index configuration has been persisted.The index entries themselves are created asynchronously. You can continue to use queries that require indexing even if the indices are not yet available. Query execution will automatically start using the index once the index entries have been written.Indexes are only supported with IndexedDb persistence. Invoke either enableIndexedDbPersistence() or enableMultiTabIndexedDbPersistence() before setting an index configuration. If IndexedDb is not enabled, any index configuration is ignored. | -| [setIndexConfiguration(firestore, json)](./firestore_.md#setindexconfiguration) | (BETA) Configures indexing for local query execution. Any previous index configuration is overridden. The Promise resolves once the index configuration has been persisted.The index entries themselves are created asynchronously. You can continue to use queries that require indexing even if the indices are not yet available. Query execution will automatically start using the index once the index entries have been written.Indexes are only supported with IndexedDb persistence. Invoke either enableIndexedDbPersistence() or enableMultiTabIndexedDbPersistence() before setting an index configuration. If IndexedDb is not enabled, any index configuration is ignored.The method accepts the JSON format exported by the Firebase CLI (firebase firestore:indexes). If the JSON format is invalid, this method throws an error. | -| [terminate(firestore)](./firestore_.md#terminate) | Terminates the provided [Firestore](./firestore_.firestore.md#firestore_class) instance.After calling terminate() only the clearIndexedDbPersistence() function may be used. Any other function will throw a FirestoreError.To restart after termination, create a new instance of FirebaseFirestore with [getFirestore()](./firestore_.md#getfirestore).Termination does not cancel any pending writes, and any promises that are awaiting a response from the server will not be resolved. If you have persistence enabled, the next time you start this instance, it will resume sending these writes to the server.Note: Under normal circumstances, calling terminate() is not required. This function is useful only when you want to force this instance to release all of its resources or in combination with clearIndexedDbPersistence() to ensure that all local state is destroyed between test runs. | -| [waitForPendingWrites(firestore)](./firestore_.md#waitforpendingwrites) | Waits until all currently pending writes for the active user have been acknowledged by the backend.The returned promise resolves immediately if there are no outstanding writes. Otherwise, the promise waits for all previously issued writes (including those written in a previous app session), but it does not wait for writes that were added after the function is called. If you want to wait for additional writes, call waitForPendingWrites() again.Any outstanding waitForPendingWrites() promises are rejected during user changes. | -| [writeBatch(firestore)](./firestore_.md#writebatch) | Creates a write batch, used for performing multiple writes as a single atomic operation. The maximum number of writes allowed in a single [WriteBatch](./firestore_.writebatch.md#writebatch_class) is 500.Unlike transactions, write batches are persisted offline and therefore are preferable when you don't need to condition your writes on read data. | -| function() | -| [deleteField()](./firestore_.md#deletefield) | Returns a sentinel for use with [updateDoc()](./firestore_lite.md#updatedoc) or [setDoc()](./firestore_lite.md#setdoc) with {merge: true} to mark a field for deletion. | -| [documentId()](./firestore_.md#documentid) | Returns a special sentinel FieldPath to refer to the ID of a document. It can be used in queries to sort or filter by the document ID. | -| [getFirestore()](./firestore_.md#getfirestore) | Returns the existing default [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. | -| [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(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. | -| function(fieldPath...) | -| [orderBy(fieldPath, directionStr)](./firestore_.md#orderby) | Creates a [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class) that sorts the query result by the specified field, optionally in descending order instead of ascending.Note: Documents that do not contain the specified field will not be present in the query result. | -| [where(fieldPath, opStr, value)](./firestore_.md#where) | Creates a [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) that enforces that documents must contain the specified field and that the value should satisfy the relation constraint provided. | -| function(fieldValues...) | -| [endAt(fieldValues)](./firestore_.md#endat) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | -| [endBefore(fieldValues)](./firestore_.md#endbefore) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | -| [startAfter(fieldValues)](./firestore_.md#startafter) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | -| [startAt(fieldValues)](./firestore_.md#startat) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | -| function(left...) | -| [aggregateQuerySnapshotEqual(left, right)](./firestore_.md#aggregatequerysnapshotequal) | Compares two AggregateQuerySnapshot instances for equality.Two AggregateQuerySnapshot instances are considered "equal" if they have underlying queries that compare equal, and the same data. | -| [queryEqual(left, right)](./firestore_.md#queryequal) | Returns true if the provided queries point to the same collection and apply the same constraints. | -| [refEqual(left, right)](./firestore_.md#refequal) | Returns true if the provided references are equal. | -| [snapshotEqual(left, right)](./firestore_.md#snapshotequal) | Returns true if the provided snapshots are equal. | -| function(limit...) | -| [limit(limit)](./firestore_.md#limit) | Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the first matching documents. | -| [limitToLast(limit)](./firestore_.md#limittolast) | Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the last matching documents.You must specify at least one orderBy clause for limitToLast queries, otherwise an exception will be thrown during execution. | -| function(logLevel...) | -| [setLogLevel(logLevel)](./firestore_.md#setloglevel) | Sets the verbosity of Cloud Firestore logs (debug, error, or silent). | -| function(n...) | -| [increment(n)](./firestore_.md#increment) | 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 increment the field's current value by the given value.If either the operand or the current field value uses floating point precision, all arithmetic follows IEEE 754 semantics. If both values are integers, values outside of JavaScript's safe number range (Number.MIN_SAFE_INTEGER to Number.MAX_SAFE_INTEGER) are also subject to precision loss. Furthermore, once processed by the Firestore backend, all integer operations are capped between -2^63 and 2^63-1.If the current field value is not of type number, or if the field does not yet exist, the transformation sets the field to the given value. | -| function(query...) | +| [endAt(snapshot)](./firestore_.md#endat) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end at the provided document (inclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | +| [endAt(fieldValues)](./firestore_.md#endat) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | +| [endBefore(snapshot)](./firestore_.md#endbefore) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | +| [endBefore(fieldValues)](./firestore_.md#endbefore) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | | [getCountFromServer(query)](./firestore_.md#getcountfromserver) | Calculates the number of documents in the result set of the given query, without actually downloading the documents.Using this function to count the documents is efficient because only the final count, not the documents' data, is downloaded. This function can even count the documents if the result set would be prohibitively large to download entirely (e.g. thousands of documents).The result received from the server is presented, unaltered, without considering any local state. That is, documents in the local cache are not taken into consideration, neither are local modifications not yet synchronized with the server. Previously-downloaded results, if any, are not used: every request using this source necessarily involves a round trip to the server. | -| [getDocs(query)](./firestore_.md#getdocs) | Executes the query and returns the results as a QuerySnapshot.Note: getDocs() attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. To specify this behavior, invoke [getDocsFromCache()](./firestore_.md#getdocsfromcache) or [getDocsFromServer()](./firestore_.md#getdocsfromserver). | -| [getDocsFromCache(query)](./firestore_.md#getdocsfromcache) | Executes the query and returns the results as a QuerySnapshot from cache. Returns an empty result set if no documents matching the query are currently cached. | -| [getDocsFromServer(query)](./firestore_.md#getdocsfromserver) | Executes the query and returns the results as a QuerySnapshot from the server. Returns an error if the network is not available. | -| [onSnapshot(query, observer)](./firestore_.md#onsnapshot) | Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | -| [onSnapshot(query, options, observer)](./firestore_.md#onsnapshot) | Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | -| [onSnapshot(query, onNext, onError, onCompletion)](./firestore_.md#onsnapshot) | Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | -| [onSnapshot(query, options, onNext, onError, onCompletion)](./firestore_.md#onsnapshot) | Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | -| [query(query, queryConstraints)](./firestore_.md#query) | Creates a new immutable instance of [Query](./firestore_.query.md#query_class) that is extended to also include additional query constraints. | -| function(reference...) | -| [addDoc(reference, data)](./firestore_.md#adddoc) | Add a new document to specified CollectionReference with the given data, assigning it a document ID automatically. | -| [collection(reference, path, pathSegments)](./firestore_.md#collection) | Gets a CollectionReference instance that refers to a subcollection of reference at the the specified relative path. | -| [collection(reference, path, pathSegments)](./firestore_.md#collection) | Gets a CollectionReference instance that refers to a subcollection of reference at the the specified relative path. | -| [deleteDoc(reference)](./firestore_.md#deletedoc) | Deletes the document referred to by the specified DocumentReference. | -| [doc(reference, path, pathSegments)](./firestore_.md#doc) | Gets a DocumentReference instance that refers to a document within reference at the specified relative path. If no path is specified, an automatically-generated unique ID will be used for the returned DocumentReference. | -| [doc(reference, path, pathSegments)](./firestore_.md#doc) | Gets a DocumentReference instance that refers to a document within reference at the specified relative path. | | [getDoc(reference)](./firestore_.md#getdoc) | Reads the document referred to by this DocumentReference.Note: getDoc() attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. To specify this behavior, invoke [getDocFromCache()](./firestore_.md#getdocfromcache) or [getDocFromServer()](./firestore_.md#getdocfromserver). | | [getDocFromCache(reference)](./firestore_.md#getdocfromcache) | Reads the document referred to by this DocumentReference from cache. Returns an error if the document is not currently cached. | | [getDocFromServer(reference)](./firestore_.md#getdocfromserver) | Reads the document referred to by this DocumentReference from the server. Returns an error if the network is not available. | +| [getDocs(query)](./firestore_.md#getdocs) | Executes the query and returns the results as a QuerySnapshot.Note: getDocs() attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. To specify this behavior, invoke [getDocsFromCache()](./firestore_.md#getdocsfromcache) or [getDocsFromServer()](./firestore_.md#getdocsfromserver). | +| [getDocsFromCache(query)](./firestore_.md#getdocsfromcache) | Executes the query and returns the results as a QuerySnapshot from cache. Returns an error if the document is not currently cached. | +| [getDocsFromServer(query)](./firestore_.md#getdocsfromserver) | Executes the query and returns the results as a QuerySnapshot from the server. Returns an error if the network is not available. | +| [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()](./firestore_.md#getfirestore) | Returns the existing default [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. | +| [increment(n)](./firestore_.md#increment) | 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 increment the field's current value by the given value.If either the operand or the current field value uses floating point precision, all arithmetic follows IEEE 754 semantics. If both values are integers, values outside of JavaScript's safe number range (Number.MIN_SAFE_INTEGER to Number.MAX_SAFE_INTEGER) are also subject to precision loss. Furthermore, once processed by the Firestore backend, all integer operations are capped between -2^63 and 2^63-1.If the current field value is not of type number, or if the field does not yet exist, the transformation sets the field to the given value. | +| [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). | +| [limit(limit)](./firestore_.md#limit) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that only returns the first matching documents. | +| [limitToLast(limit)](./firestore_.md#limittolast) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that only returns the last matching documents.You must specify at least one orderBy clause for limitToLast queries, otherwise an exception will be thrown during execution. | +| [loadBundle(firestore, bundleData)](./firestore_.md#loadbundle) | Loads a Firestore bundle into the local cache. | +| [namedQuery(firestore, name)](./firestore_.md#namedquery) | Reads a Firestore [Query](./firestore_.query.md#query_class) 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](./firestore_.query.md#query_class) by name. | | [onSnapshot(reference, observer)](./firestore_.md#onsnapshot) | Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | | [onSnapshot(reference, options, observer)](./firestore_.md#onsnapshot) | Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | | [onSnapshot(reference, onNext, onError, onCompletion)](./firestore_.md#onsnapshot) | Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | | [onSnapshot(reference, options, onNext, onError, onCompletion)](./firestore_.md#onsnapshot) | Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | +| [onSnapshot(query, observer)](./firestore_.md#onsnapshot) | Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | +| [onSnapshot(query, options, observer)](./firestore_.md#onsnapshot) | Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | +| [onSnapshot(query, onNext, onError, onCompletion)](./firestore_.md#onsnapshot) | Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | +| [onSnapshot(query, options, onNext, onError, onCompletion)](./firestore_.md#onsnapshot) | Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | +| [onSnapshotsInSync(firestore, observer)](./firestore_.md#onsnapshotsinsync) | Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners.NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use SnapshotMetadata in the individual listeners to determine if a snapshot is from the cache or the server. | +| [onSnapshotsInSync(firestore, onSync)](./firestore_.md#onsnapshotsinsync) | Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners.NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use SnapshotMetadata in the individual listeners to determine if a snapshot is from the cache or the server. | +| [orderBy(fieldPath, directionStr)](./firestore_.md#orderby) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that sorts the query result by the specified field, optionally in descending order instead of ascending. | +| [query(query, queryConstraints)](./firestore_.md#query) | Creates a new immutable instance of [Query](./firestore_.query.md#query_class) that is extended to also include additional query constraints. | +| [queryEqual(left, right)](./firestore_.md#queryequal) | Returns true if the provided queries point to the same collection and apply the same constraints. | +| [refEqual(left, right)](./firestore_.md#refequal) | Returns true if the provided references are equal. | +| [runTransaction(firestore, updateFunction, options)](./firestore_.md#runtransaction) | Executes the given updateFunction and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, Cloud Firestore retries the updateFunction. If it fails to commit after 5 attempts, the transaction fails.The maximum number of writes allowed in a single transaction is 500. | +| [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. | | [setDoc(reference, data)](./firestore_.md#setdoc) | Writes to the document referred to by this DocumentReference. If the document does not yet exist, it will be created. | | [setDoc(reference, data, options)](./firestore_.md#setdoc) | Writes to the document referred to by the specified DocumentReference. If the document does not yet exist, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document. | +| [setIndexConfiguration(firestore, configuration)](./firestore_.md#setindexconfiguration) | (BETA) Configures indexing for local query execution. Any previous index configuration is overridden. The Promise resolves once the index configuration has been persisted.The index entries themselves are created asynchronously. You can continue to use queries that require indexing even if the indices are not yet available. Query execution will automatically start using the index once the index entries have been written.Indexes are only supported with IndexedDb persistence. Invoke either enableIndexedDbPersistence() or enableMultiTabIndexedDbPersistence() before setting an index configuration. If IndexedDb is not enabled, any index configuration is ignored. | +| [setIndexConfiguration(firestore, json)](./firestore_.md#setindexconfiguration) | (BETA) Configures indexing for local query execution. Any previous index configuration is overridden. The Promise resolves once the index configuration has been persisted.The index entries themselves are created asynchronously. You can continue to use queries that require indexing even if the indices are not yet available. Query execution will automatically start using the index once the index entries have been written.Indexes are only supported with IndexedDb persistence. Invoke either enableIndexedDbPersistence() or enableMultiTabIndexedDbPersistence() before setting an index configuration. If IndexedDb is not enabled, any index configuration is ignored.The method accepts the JSON format exported by the Firebase CLI (firebase firestore:indexes). If the JSON format is invalid, this method throws an error. | +| [setLogLevel(logLevel)](./firestore_.md#setloglevel) | Sets the verbosity of Cloud Firestore logs (debug, error, or silent). | +| [snapshotEqual(left, right)](./firestore_.md#snapshotequal) | Returns true if the provided snapshots are equal. | +| [startAfter(snapshot)](./firestore_.md#startafter) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | +| [startAfter(fieldValues)](./firestore_.md#startafter) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | +| [startAt(snapshot)](./firestore_.md#startat) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of this query. | +| [startAt(fieldValues)](./firestore_.md#startat) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | +| [terminate(firestore)](./firestore_.md#terminate) | Terminates the provided [Firestore](./firestore_.firestore.md#firestore_class) instance.After calling terminate() only the clearIndexedDbPersistence() function may be used. Any other function will throw a FirestoreError.To restart after termination, create a new instance of FirebaseFirestore with [getFirestore()](./firestore_.md#getfirestore).Termination does not cancel any pending writes, and any promises that are awaiting a response from the server will not be resolved. If you have persistence enabled, the next time you start this instance, it will resume sending these writes to the server.Note: Under normal circumstances, calling terminate() is not required. This function is useful only when you want to force this instance to release all of its resources or in combination with clearIndexedDbPersistence() to ensure that all local state is destroyed between test runs. | | [updateDoc(reference, data)](./firestore_.md#updatedoc) | Updates fields in the document referred to by the specified DocumentReference. The update will fail if applied to a document that does not exist. | | [updateDoc(reference, field, value, moreFieldsAndValues)](./firestore_.md#updatedoc) | Updates fields in the document referred to by the specified DocumentReference The update will fail if applied to a document that does not exist.Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects. | -| function(snapshot...) | -| [endAt(snapshot)](./firestore_.md#endat) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided document (inclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | -| [endBefore(snapshot)](./firestore_.md#endbefore) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | -| [startAfter(snapshot)](./firestore_.md#startafter) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | -| [startAt(snapshot)](./firestore_.md#startat) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of this query. | +| [waitForPendingWrites(firestore)](./firestore_.md#waitforpendingwrites) | Waits until all currently pending writes for the active user have been acknowledged by the backend.The returned promise resolves immediately if there are no outstanding writes. Otherwise, the promise waits for all previously issued writes (including those written in a previous app session), but it does not wait for writes that were added after the function is called. If you want to wait for additional writes, call waitForPendingWrites() again.Any outstanding waitForPendingWrites() promises are rejected during user changes. | +| [where(fieldPath, opStr, value)](./firestore_.md#where) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that enforces that documents must contain the specified field and that the value should satisfy the relation constraint provided. | +| [writeBatch(firestore)](./firestore_.md#writebatch) | Creates a write batch, used for performing multiple writes as a single atomic operation. The maximum number of writes allowed in a single [WriteBatch](./firestore_.writebatch.md#writebatch_class) is 500.Unlike transactions, write batches are persisted offline and therefore are preferable when you don't need to condition your writes on read data. | ## Classes @@ -117,14 +104,9 @@ https://github.com/firebase/firebase-js-sdk | [GeoPoint](./firestore_.geopoint.md#geopoint_class) | An immutable object representing a geographic location in Firestore. The location is represented as latitude/longitude pair.Latitude values are in the range of \[-90, 90\]. Longitude values are in the range of \[-180, 180\]. | | [LoadBundleTask](./firestore_.loadbundletask.md#loadbundletask_class) | 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>. | | [Query](./firestore_.query.md#query_class) | A Query refers to a query which you can read or listen to. You can also construct refined Query objects by adding filters and ordering. | -| [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) | A QueryConstraint is used to narrow the set of documents returned by a Firestore query. QueryConstraints are created by invoking [where()](./firestore_.md#where), [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit), [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryConstraint. | +| [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) | A QueryConstraint is used to narrow the set of documents returned by a Firestore query. QueryConstraints are created by invoking [where()](./firestore_.md#where), [orderBy()](./firestore_.md#orderby), [startAt()](./firestore_.md#startat), [startAfter()](./firestore_.md#startafter), , [endAt()](./firestore_.md#endat), [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryConstraint. | | [QueryDocumentSnapshot](./firestore_.querydocumentsnapshot.md#querydocumentsnapshot_class) | A QueryDocumentSnapshot contains data read from a document in your Firestore database as part of a query. The document is guaranteed to exist and its data can be extracted with .data() or .get(<field>) to get a specific field.A QueryDocumentSnapshot offers the same API surface as a DocumentSnapshot. Since query results contain only existing documents, the exists property will always be true and data() will never return 'undefined'. | -| [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) | A QueryEndAtConstraint is used to exclude documents from the end of a result set returned by a Firestore query. QueryEndAtConstraints are created by invoking [endAt()](./firestore_.md#endat) or [endBefore()](./firestore_.md#endbefore) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryEndAtConstraint. | -| [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) | A QueryFieldFilterConstraint is used to narrow the set of documents returned by a Firestore query by filtering on one or more document fields. QueryFieldFilterConstraints are created by invoking [where()](./firestore_.md#where) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryFieldFilterConstraint. | -| [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) | A QueryLimitConstraint is used to limit the number of documents returned by a Firestore query. QueryLimitConstraints are created by invoking [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryLimitConstraint. | -| [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class) | A QueryOrderByConstraint is used to sort the set of documents returned by a Firestore query. QueryOrderByConstraints are created by invoking [orderBy()](./firestore_.md#orderby) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryOrderByConstraint.Note: Documents that do not contain the orderBy field will not be present in the query result. | | [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class) | A QuerySnapshot contains zero or more DocumentSnapshot objects representing the results of a query. The documents can be accessed as an array via the docs property or enumerated using the forEach method. The number of documents can be determined via the empty and size properties. | -| [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) | A QueryStartAtConstraint is used to exclude documents from the start of a result set returned by a Firestore query. QueryStartAtConstraints are created by invoking [startAt()](./firestore_.md#startat) or [startAfter()](./firestore_.md#startafter) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryStartAtConstraint. | | [SnapshotMetadata](./firestore_.snapshotmetadata.md#snapshotmetadata_class) | Metadata about a snapshot, describing the state of the snapshot. | | [Timestamp](./firestore_.timestamp.md#timestamp_class) | A Timestamp represents a point in time independent of any time zone or calendar, represented as seconds and fractions of seconds at nanosecond resolution in UTC Epoch time.It is encoded using the Proleptic Gregorian Calendar which extends the Gregorian calendar backwards to year one. It is encoded assuming all minutes are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.For examples and further specifications, refer to the [Timestamp definition](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto). | | [Transaction](./firestore_.transaction.md#transaction_class) | A reference to a transaction.The Transaction object passed to a transaction's updateFunction provides the methods to read and write data within the transaction context. See [runTransaction()](./firestore_.md#runtransaction). | @@ -170,7 +152,6 @@ https://github.com/firebase/firebase-js-sdk | [PartialWithFieldValue](./firestore_.md#partialwithfieldvalue) | Similar to Typescript's Partial<T>, but allows nested fields to be omitted and FieldValues to be passed in as property values. | | [Primitive](./firestore_.md#primitive) | Primitive types. | | [QueryConstraintType](./firestore_.md#queryconstrainttype) | Describes the different query constraints available in this SDK. | -| [QueryNonFilterConstraint](./firestore_.md#querynonfilterconstraint) | QueryNonFilterConstraint is a helper union type that represents QueryConstraints which are used to narrow or order the set of documents, but that do not explicitly filter on a document field. QueryNonFilterConstraints are created by invoking [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains the QueryConstraint. | | [SetOptions](./firestore_.md#setoptions) | An options object that configures the behavior of [setDoc()](./firestore_lite.md#setdoc), and calls. These calls can be configured to perform granular merges instead of overwriting the target documents in their entirety by providing a SetOptions with merge: true. | | [TaskState](./firestore_.md#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. | | [UnionToIntersection](./firestore_.md#uniontointersection) | Given a union type U = T1 | T2 | ..., returns an intersected type (T1 & T2 & ...).Uses distributive conditional types and inference from conditional types. This works because multiple candidates for the same type variable in contra-variant positions causes an intersection type to be inferred. https://www.typescriptlang.org/docs/handbook/advanced-types.html\#type-inference-in-conditional-types https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection-type | @@ -178,51 +159,97 @@ https://github.com/firebase/firebase-js-sdk | [WhereFilterOp](./firestore_.md#wherefilterop) | Filter conditions in a [where()](./firestore_.md#where) clause are specified using the strings '&lt;', '&lt;=', '==', '!=', '&gt;=', '&gt;', 'array-contains', 'in', 'array-contains-any', and 'not-in'. | | [WithFieldValue](./firestore_.md#withfieldvalue) | Allows FieldValues to be passed in as a property value while maintaining type safety. | -## getFirestore() +## addDoc() -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. +Add a new document to specified `CollectionReference` with the given data, assigning it a document ID automatically. Signature: ```typescript -export declare function getFirestore(app: FirebaseApp): Firestore; +export declare function addDoc(reference: CollectionReference, data: WithFieldValue): Promise>; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance that the returned [Firestore](./firestore_.firestore.md#firestore_class) instance is associated with. | +| reference | [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | A reference to the collection to add this document to. | +| data | [WithFieldValue](./firestore_.md#withfieldvalue)<T> | An Object containing the data for the new document. | Returns: -[Firestore](./firestore_.firestore.md#firestore_class) +Promise<[DocumentReference](./firestore_.documentreference.md#documentreference_class)<T>> -The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. +A `Promise` resolved with a `DocumentReference` pointing to the newly created document after it has been written to the backend (Note that it won't resolve while you're offline). -## initializeFirestore() +## aggregateQuerySnapshotEqual() -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). +Compares two `AggregateQuerySnapshot` instances for equality. + +Two `AggregateQuerySnapshot` instances are considered "equal" if they have underlying queries that compare equal, and the same data. Signature: ```typescript -export declare function initializeFirestore(app: FirebaseApp, settings: FirestoreSettings, databaseId?: string): Firestore; +export declare function aggregateQuerySnapshotEqual(left: AggregateQuerySnapshot, right: AggregateQuerySnapshot): boolean; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) with which the [Firestore](./firestore_.firestore.md#firestore_class) instance will be associated. | -| settings | [FirestoreSettings](./firestore_.firestoresettings.md#firestoresettings_interface) | A settings object to configure the [Firestore](./firestore_.firestore.md#firestore_class) instance. | -| databaseId | string | The name of database. | +| left | [AggregateQuerySnapshot](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<T> | The first AggregateQuerySnapshot to compare. | +| right | [AggregateQuerySnapshot](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<T> | The second AggregateQuerySnapshot to compare. | Returns: -[Firestore](./firestore_.firestore.md#firestore_class) +boolean -A newly initialized [Firestore](./firestore_.firestore.md#firestore_class) instance. +`true` if the objects are "equal", as defined above, or `false` otherwise. + +## 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. + +Signature: + +```typescript +export declare function arrayRemove(...elements: unknown[]): FieldValue; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| elements | unknown\[\] | The elements to remove from the array. | + +Returns: + +[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) + +The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()` + +## 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. + +Signature: + +```typescript +export declare function arrayUnion(...elements: unknown[]): FieldValue; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| elements | unknown\[\] | The elements to union into the array. | + +Returns: + +[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) + +The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()`. ## clearIndexedDbPersistence() @@ -278,6 +305,62 @@ The `CollectionReference` instance. If the final path has an even number of segments and does not point to a collection. +## collection() + +Gets a `CollectionReference` instance that refers to a subcollection of `reference` at the the specified relative path. + +Signature: + +```typescript +export declare function collection(reference: CollectionReference, path: string, ...pathSegments: string[]): CollectionReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<unknown> | A reference to a collection. | +| path | string | A slash-separated path to a collection. | +| pathSegments | string\[\] | Additional path segments to apply relative to the first argument. | + +Returns: + +[CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> + +The `CollectionReference` instance. + +## Exceptions + +If the final path has an even number of segments and does not point to a collection. + +## collection() + +Gets a `CollectionReference` instance that refers to a subcollection of `reference` at the the specified relative path. + +Signature: + +```typescript +export declare function collection(reference: DocumentReference, path: string, ...pathSegments: string[]): CollectionReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class) | A reference to a Firestore document. | +| path | string | A slash-separated path to a collection. | +| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | + +Returns: + +[CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> + +The `CollectionReference` instance. + +## Exceptions + +If the final path has an even number of segments and does not point to a collection. + ## collectionGroup() Creates and returns a new `Query` instance that includes all documents in the database that are contained in a collection or subcollection with the given `collectionId`. @@ -328,6 +411,41 @@ export declare function connectFirestoreEmulator(firestore: Firestore, host: str void +## deleteDoc() + +Deletes the document referred to by the specified `DocumentReference`. + +Signature: + +```typescript +export declare function deleteDoc(reference: DocumentReference): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to the document to delete. | + +Returns: + +Promise<void> + +A Promise resolved once the document has been successfully deleted from the backend (note that it won't resolve while you're offline). + +## deleteField() + +Returns a sentinel for use with [updateDoc()](./firestore_lite.md#updatedoc) or [setDoc()](./firestore_lite.md#setdoc) with `{merge: true}` to mark a field for deletion. + +Signature: + +```typescript +export declare function deleteField(): FieldValue; +``` +Returns: + +[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) + ## disableNetwork() Disables network usage for this instance. It can be re-enabled via [enableNetwork()](./firestore_.md#enablenetwork). While the network is disabled, any snapshot listeners, `getDoc()` or `getDocs()` calls will return results from cache, and any write operations will be queued until the network is restored. @@ -378,702 +496,503 @@ The `DocumentReference` instance. If the final path has an odd number of segments and does not point to a document. -## enableIndexedDbPersistence() - -Attempts to enable persistent storage, if possible. - -Must be called before any other functions (other than [initializeFirestore()](./firestore_.md#initializefirestore), [getFirestore()](./firestore_.md#getfirestore) or [clearIndexedDbPersistence()](./firestore_.md#clearindexeddbpersistence). - -If this fails, `enableIndexedDbPersistence()` will reject the promise it returns. Note that even after this failure, the [Firestore](./firestore_.firestore.md#firestore_class) instance will remain usable, however offline persistence will be disabled. - -There are several reasons why this can fail, which can be identified by the `code` on the error. +## doc() -\* failed-precondition: The app is already open in another browser tab. \* unimplemented: The browser is incompatible with the offline persistence implementation. +Gets a `DocumentReference` instance that refers to a document within `reference` at the specified relative path. If no path is specified, an automatically-generated unique ID will be used for the returned `DocumentReference`. Signature: ```typescript -export declare function enableIndexedDbPersistence(firestore: Firestore, persistenceSettings?: PersistenceSettings): Promise; +export declare function doc(reference: CollectionReference, path?: string, ...pathSegments: string[]): DocumentReference; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to enable persistence for. | -| persistenceSettings | [PersistenceSettings](./firestore_.persistencesettings.md#persistencesettings_interface) | Optional settings object to configure persistence. | - -Returns: - -Promise<void> - -A `Promise` that represents successfully enabling persistent storage. - -## enableMultiTabIndexedDbPersistence() - -Attempts to enable multi-tab persistent storage, if possible. If enabled across all tabs, all operations share access to local persistence, including shared execution of queries and latency-compensated local document updates across all connected instances. - -If this fails, `enableMultiTabIndexedDbPersistence()` will reject the promise it returns. Note that even after this failure, the [Firestore](./firestore_.firestore.md#firestore_class) instance will remain usable, however offline persistence will be disabled. - -There are several reasons why this can fail, which can be identified by the `code` on the error. - -\* failed-precondition: The app is already open in another browser tab and multi-tab is not enabled. \* unimplemented: The browser is incompatible with the offline persistence implementation. - -Signature: - -```typescript -export declare function enableMultiTabIndexedDbPersistence(firestore: Firestore): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to enable persistence for. | +| reference | [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | A reference to a collection. | +| path | string | A slash-separated path to a document. Has to be omitted to use auto-genrated IDs. | +| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | Returns: -Promise<void> - -A `Promise` that represents successfully enabling persistent storage. - -## enableNetwork() - -Re-enables use of the network for this [Firestore](./firestore_.firestore.md#firestore_class) instance after a prior call to [disableNetwork()](./firestore_.md#disablenetwork). - -Signature: - -```typescript -export declare function enableNetwork(firestore: Firestore): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | +[DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> -Returns: +The `DocumentReference` instance. -Promise<void> +## Exceptions -A `Promise` that is resolved once the network has been enabled. +If the final path has an odd number of segments and does not point to a document. -## loadBundle() +## doc() -Loads a Firestore bundle into the local cache. +Gets a `DocumentReference` instance that refers to a document within `reference` at the specified relative path. Signature: ```typescript -export declare function loadBundle(firestore: Firestore, bundleData: ReadableStream | ArrayBuffer | string): LoadBundleTask; +export declare function doc(reference: DocumentReference, path: string, ...pathSegments: string[]): DocumentReference; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to load bundles for. | -| bundleData | ReadableStream<Uint8Array> \| ArrayBuffer \| string | An object representing the bundle to be loaded. Valid objects are ArrayBuffer, ReadableStream<Uint8Array> or string. | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to a Firestore document. | +| path | string | A slash-separated path to a document. | +| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | Returns: -[LoadBundleTask](./firestore_.loadbundletask.md#loadbundletask_class) - -A `LoadBundleTask` object, which notifies callers with progress updates, and completion or error events. It can be used as a `Promise`. - -## namedQuery() - -Reads a Firestore [Query](./firestore_.query.md#query_class) 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](./firestore_.query.md#query_class) by name. - -Signature: - -```typescript -export declare function namedQuery(firestore: Firestore, name: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to read the query from. | -| name | string | The name of the query. | - -Returns: +[DocumentReference](./firestore_.documentreference.md#documentreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> -Promise<[Query](./firestore_.query.md#query_class) \| null> +The `DocumentReference` instance. -A `Promise` that is resolved with the Query or `null`. +## Exceptions -## onSnapshotsInSync() +If the final path has an odd number of segments and does not point to a document. -Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners. +## documentId() -NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use SnapshotMetadata in the individual listeners to determine if a snapshot is from the cache or the server. +Returns a special sentinel `FieldPath` to refer to the ID of a document. It can be used in queries to sort or filter by the document ID. Signature: ```typescript -export declare function onSnapshotsInSync(firestore: Firestore, observer: { - next?: (value: void) => void; - error?: (error: FirestoreError) => void; - complete?: () => void; -}): Unsubscribe; +export declare function documentId(): FieldPath; ``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The instance of Firestore for synchronizing snapshots. | -| observer | { next?: (value: void) => void; error?: (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void; complete?: () => void; } | A single object containing next and error callbacks. | - Returns: -[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) - -An unsubscribe function that can be called to cancel the snapshot listener. - -## onSnapshotsInSync() - -Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners. - -NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use `SnapshotMetadata` in the individual listeners to determine if a snapshot is from the cache or the server. - -Signature: - -```typescript -export declare function onSnapshotsInSync(firestore: Firestore, onSync: () => void): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The Firestore instance for synchronizing snapshots. | -| onSync | () => void | A callback to be called every time all snapshot listeners are in sync with each other. | +[FieldPath](./firestore_.fieldpath.md#fieldpath_class) -Returns: +## enableIndexedDbPersistence() -[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) +Attempts to enable persistent storage, if possible. -An unsubscribe function that can be called to cancel the snapshot listener. +Must be called before any other functions (other than [initializeFirestore()](./firestore_.md#initializefirestore), [getFirestore()](./firestore_.md#getfirestore) or [clearIndexedDbPersistence()](./firestore_.md#clearindexeddbpersistence). -## runTransaction() +If this fails, `enableIndexedDbPersistence()` will reject the promise it returns. Note that even after this failure, the [Firestore](./firestore_.firestore.md#firestore_class) instance will remain usable, however offline persistence will be disabled. -Executes the given `updateFunction` and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, Cloud Firestore retries the `updateFunction`. If it fails to commit after 5 attempts, the transaction fails. +There are several reasons why this can fail, which can be identified by the `code` on the error. -The maximum number of writes allowed in a single transaction is 500. +\* failed-precondition: The app is already open in another browser tab. \* unimplemented: The browser is incompatible with the offline persistence implementation. Signature: ```typescript -export declare function runTransaction(firestore: Firestore, updateFunction: (transaction: Transaction) => Promise, options?: TransactionOptions): Promise; +export declare function enableIndexedDbPersistence(firestore: Firestore, persistenceSettings?: PersistenceSettings): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | A reference to the Firestore database to run this transaction against. | -| updateFunction | (transaction: [Transaction](./firestore_.transaction.md#transaction_class)) => Promise<T> | The function to execute within the transaction context. | -| options | [TransactionOptions](./firestore_.transactionoptions.md#transactionoptions_interface) | An options object to configure maximum number of attempts to commit. | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to enable persistence for. | +| persistenceSettings | [PersistenceSettings](./firestore_.persistencesettings.md#persistencesettings_interface) | Optional settings object to configure persistence. | Returns: -Promise<T> +Promise<void> -If the transaction completed successfully or was explicitly aborted (the `updateFunction` returned a failed promise), the promise returned by the `updateFunction `is returned here. Otherwise, if the transaction failed, a rejected promise with the corresponding failure error is returned. +A `Promise` that represents successfully enabling persistent storage. -## setIndexConfiguration() +## enableMultiTabIndexedDbPersistence() -> 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. -> +Attempts to enable multi-tab persistent storage, if possible. If enabled across all tabs, all operations share access to local persistence, including shared execution of queries and latency-compensated local document updates across all connected instances. -Configures indexing for local query execution. Any previous index configuration is overridden. The `Promise` resolves once the index configuration has been persisted. +If this fails, `enableMultiTabIndexedDbPersistence()` will reject the promise it returns. Note that even after this failure, the [Firestore](./firestore_.firestore.md#firestore_class) instance will remain usable, however offline persistence will be disabled. -The index entries themselves are created asynchronously. You can continue to use queries that require indexing even if the indices are not yet available. Query execution will automatically start using the index once the index entries have been written. +There are several reasons why this can fail, which can be identified by the `code` on the error. -Indexes are only supported with IndexedDb persistence. Invoke either `enableIndexedDbPersistence()` or `enableMultiTabIndexedDbPersistence()` before setting an index configuration. If IndexedDb is not enabled, any index configuration is ignored. +\* failed-precondition: The app is already open in another browser tab and multi-tab is not enabled. \* unimplemented: The browser is incompatible with the offline persistence implementation. Signature: ```typescript -export declare function setIndexConfiguration(firestore: Firestore, configuration: IndexConfiguration): Promise; +export declare function enableMultiTabIndexedDbPersistence(firestore: Firestore): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to configure indexes for. | -| configuration | [IndexConfiguration](./firestore_.indexconfiguration.md#indexconfiguration_interface) | The index definition. | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to enable persistence for. | Returns: Promise<void> -A `Promise` that resolves once all indices are successfully configured. - -## Exceptions - -FirestoreError if the JSON format is invalid. - -## setIndexConfiguration() - -> 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. -> - -Configures indexing for local query execution. Any previous index configuration is overridden. The `Promise` resolves once the index configuration has been persisted. - -The index entries themselves are created asynchronously. You can continue to use queries that require indexing even if the indices are not yet available. Query execution will automatically start using the index once the index entries have been written. +A `Promise` that represents successfully enabling persistent storage. -Indexes are only supported with IndexedDb persistence. Invoke either `enableIndexedDbPersistence()` or `enableMultiTabIndexedDbPersistence()` before setting an index configuration. If IndexedDb is not enabled, any index configuration is ignored. +## enableNetwork() -The method accepts the JSON format exported by the Firebase CLI (`firebase firestore:indexes`). If the JSON format is invalid, this method throws an error. +Re-enables use of the network for this [Firestore](./firestore_.firestore.md#firestore_class) instance after a prior call to [disableNetwork()](./firestore_.md#disablenetwork). Signature: ```typescript -export declare function setIndexConfiguration(firestore: Firestore, json: string): Promise; +export declare function enableNetwork(firestore: Firestore): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to configure indexes for. | -| json | string | The JSON format exported by the Firebase CLI. | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | Returns: Promise<void> -A `Promise` that resolves once all indices are successfully configured. - -## Exceptions - -FirestoreError if the JSON format is invalid. - -## terminate() - -Terminates the provided [Firestore](./firestore_.firestore.md#firestore_class) instance. - -After calling `terminate()` only the `clearIndexedDbPersistence()` function may be used. Any other function will throw a `FirestoreError`. - -To restart after termination, create a new instance of FirebaseFirestore with [getFirestore()](./firestore_.md#getfirestore). +A `Promise` that is resolved once the network has been enabled. -Termination does not cancel any pending writes, and any promises that are awaiting a response from the server will not be resolved. If you have persistence enabled, the next time you start this instance, it will resume sending these writes to the server. +## endAt() -Note: Under normal circumstances, calling `terminate()` is not required. This function is useful only when you want to force this instance to release all of its resources or in combination with `clearIndexedDbPersistence()` to ensure that all local state is destroyed between test runs. +Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end at the provided document (inclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. Signature: ```typescript -export declare function terminate(firestore: Firestore): Promise; +export declare function endAt(snapshot: DocumentSnapshot): QueryConstraint; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | +| snapshot | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to end at. | Returns: -Promise<void> +[QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) -A `Promise` that is resolved when the instance has been successfully terminated. +A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()` -## waitForPendingWrites() - -Waits until all currently pending writes for the active user have been acknowledged by the backend. - -The returned promise resolves immediately if there are no outstanding writes. Otherwise, the promise waits for all previously issued writes (including those written in a previous app session), but it does not wait for writes that were added after the function is called. If you want to wait for additional writes, call `waitForPendingWrites()` again. +## endAt() -Any outstanding `waitForPendingWrites()` promises are rejected during user changes. +Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. Signature: ```typescript -export declare function waitForPendingWrites(firestore: Firestore): Promise; +export declare function endAt(...fieldValues: unknown[]): QueryConstraint; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | +| fieldValues | unknown\[\] | The field values to end this query at, in order of the query's order by. | Returns: -Promise<void> +[QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) -A `Promise` which resolves when all currently pending writes have been acknowledged by the backend. +A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()` -## writeBatch() +## endBefore() -Creates a write batch, used for performing multiple writes as a single atomic operation. The maximum number of writes allowed in a single [WriteBatch](./firestore_.writebatch.md#writebatch_class) is 500. - -Unlike transactions, write batches are persisted offline and therefore are preferable when you don't need to condition your writes on read data. +Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. Signature: ```typescript -export declare function writeBatch(firestore: Firestore): WriteBatch; +export declare function endBefore(snapshot: DocumentSnapshot): QueryConstraint; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | - -Returns: - -[WriteBatch](./firestore_.writebatch.md#writebatch_class) - -A [WriteBatch](./firestore_.writebatch.md#writebatch_class) that can be used to atomically execute multiple writes. - -## deleteField() - -Returns a sentinel for use with [updateDoc()](./firestore_lite.md#updatedoc) or [setDoc()](./firestore_lite.md#setdoc) with `{merge: true}` to mark a field for deletion. - -Signature: - -```typescript -export declare function deleteField(): FieldValue; -``` -Returns: - -[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) - -## documentId() - -Returns a special sentinel `FieldPath` to refer to the ID of a document. It can be used in queries to sort or filter by the document ID. - -Signature: - -```typescript -export declare function documentId(): FieldPath; -``` -Returns: - -[FieldPath](./firestore_.fieldpath.md#fieldpath_class) - -## getFirestore() - -Returns the existing default [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: +| snapshot | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to end before. | -```typescript -export declare function getFirestore(): Firestore; -``` Returns: -[Firestore](./firestore_.firestore.md#firestore_class) - -The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. - -## 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. - -Signature: - -```typescript -export declare function serverTimestamp(): FieldValue; -``` -Returns: +[QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) -[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) +A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()` -## arrayRemove() +## endBefore() -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. +Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. Signature: ```typescript -export declare function arrayRemove(...elements: unknown[]): FieldValue; +export declare function endBefore(...fieldValues: unknown[]): QueryConstraint; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| elements | unknown\[\] | The elements to remove from the array. | +| fieldValues | unknown\[\] | The field values to end this query before, in order of the query's order by. | Returns: -[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) +[QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) -The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()` +A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()` -## arrayUnion() +## getCountFromServer() -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. +Calculates the number of documents in the result set of the given query, without actually downloading the documents. + +Using this function to count the documents is efficient because only the final count, not the documents' data, is downloaded. This function can even count the documents if the result set would be prohibitively large to download entirely (e.g. thousands of documents). + +The result received from the server is presented, unaltered, without considering any local state. That is, documents in the local cache are not taken into consideration, neither are local modifications not yet synchronized with the server. Previously-downloaded results, if any, are not used: every request using this source necessarily involves a round trip to the server. Signature: ```typescript -export declare function arrayUnion(...elements: unknown[]): FieldValue; +export declare function getCountFromServer(query: Query): Promise; +}>>; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| elements | unknown\[\] | The elements to union into the array. | +| query | [Query](./firestore_.query.md#query_class)<unknown> | The query whose result set size to calculate. | Returns: -[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) +Promise<[AggregateQuerySnapshot](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<{ count: [AggregateField](./firestore_.aggregatefield.md#aggregatefield_class)<number>; }>> -The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()`. +A Promise that will be resolved with the count; the count can be retrieved from `snapshot.data().count`, where `snapshot` is the `AggregateQuerySnapshot` to which the returned Promise resolves. -## orderBy() +## getDoc() -Creates a [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class) that sorts the query result by the specified field, optionally in descending order instead of ascending. +Reads the document referred to by this `DocumentReference`. -Note: Documents that do not contain the specified field will not be present in the query result. +Note: `getDoc()` attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. To specify this behavior, invoke [getDocFromCache()](./firestore_.md#getdocfromcache) or [getDocFromServer()](./firestore_.md#getdocfromserver). Signature: ```typescript -export declare function orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDirection): QueryOrderByConstraint; +export declare function getDoc(reference: DocumentReference): Promise>; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| fieldPath | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The field to sort by. | -| directionStr | [OrderByDirection](./firestore_.md#orderbydirection) | Optional direction to sort by ('asc' or 'desc'). If not specified, order will be ascending. | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | The reference of the document to fetch. | Returns: -[QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class) +Promise<[DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>> -The created [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class). +A Promise resolved with a `DocumentSnapshot` containing the current document contents. -## where() +## getDocFromCache() -Creates a [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) that enforces that documents must contain the specified field and that the value should satisfy the relation constraint provided. +Reads the document referred to by this `DocumentReference` from cache. Returns an error if the document is not currently cached. Signature: ```typescript -export declare function where(fieldPath: string | FieldPath, opStr: WhereFilterOp, value: unknown): QueryFieldFilterConstraint; +export declare function getDocFromCache(reference: DocumentReference): Promise>; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| fieldPath | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The path to compare | -| opStr | [WhereFilterOp](./firestore_.md#wherefilterop) | The operation string (e.g "&lt;", "&lt;=", "==", "&lt;", "&lt;=", "!="). | -| value | unknown | The value for comparison | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | | Returns: -[QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) +Promise<[DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>> -The created [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class). +A `Promise` resolved with a `DocumentSnapshot` containing the current document contents. -## endAt() +## getDocFromServer() -Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. +Reads the document referred to by this `DocumentReference` from the server. Returns an error if the network is not available. Signature: ```typescript -export declare function endAt(...fieldValues: unknown[]): QueryEndAtConstraint; +export declare function getDocFromServer(reference: DocumentReference): Promise>; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| fieldValues | unknown\[\] | The field values to end this query at, in order of the query's order by. | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | | Returns: -[QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) +Promise<[DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>> -A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` +A `Promise` resolved with a `DocumentSnapshot` containing the current document contents. -## endBefore() +## getDocs() -Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. +Executes the query and returns the results as a `QuerySnapshot`. + +Note: `getDocs()` attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. To specify this behavior, invoke [getDocsFromCache()](./firestore_.md#getdocsfromcache) or [getDocsFromServer()](./firestore_.md#getdocsfromserver). Signature: ```typescript -export declare function endBefore(...fieldValues: unknown[]): QueryEndAtConstraint; +export declare function getDocs(query: Query): Promise>; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| fieldValues | unknown\[\] | The field values to end this query before, in order of the query's order by. | +| query | [Query](./firestore_.query.md#query_class)<T> | | Returns: -[QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) +Promise<[QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>> -A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` +A `Promise` that will be resolved with the results of the query. -## startAfter() +## getDocsFromCache() -Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. +Executes the query and returns the results as a `QuerySnapshot` from cache. Returns an error if the document is not currently cached. Signature: ```typescript -export declare function startAfter(...fieldValues: unknown[]): QueryStartAtConstraint; +export declare function getDocsFromCache(query: Query): Promise>; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| fieldValues | unknown\[\] | The field values to start this query after, in order of the query's order by. | +| query | [Query](./firestore_.query.md#query_class)<T> | | Returns: -[QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) +Promise<[QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>> -A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()` +A `Promise` that will be resolved with the results of the query. -## startAt() +## getDocsFromServer() -Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. +Executes the query and returns the results as a `QuerySnapshot` from the server. Returns an error if the network is not available. Signature: ```typescript -export declare function startAt(...fieldValues: unknown[]): QueryStartAtConstraint; +export declare function getDocsFromServer(query: Query): Promise>; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| fieldValues | unknown\[\] | The field values to start this query at, in order of the query's order by. | +| query | [Query](./firestore_.query.md#query_class)<T> | | Returns: -[QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) - -A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()`. +Promise<[QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>> -## aggregateQuerySnapshotEqual() +A `Promise` that will be resolved with the results of the query. -Compares two `AggregateQuerySnapshot` instances for equality. +## getFirestore() -Two `AggregateQuerySnapshot` instances are considered "equal" if they have underlying queries that compare equal, and the same data. +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. Signature: ```typescript -export declare function aggregateQuerySnapshotEqual(left: AggregateQuerySnapshot, right: AggregateQuerySnapshot): boolean; +export declare function getFirestore(app: FirebaseApp): Firestore; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| left | [AggregateQuerySnapshot](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<T> | The first AggregateQuerySnapshot to compare. | -| right | [AggregateQuerySnapshot](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<T> | The second AggregateQuerySnapshot to compare. | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance that the returned [Firestore](./firestore_.firestore.md#firestore_class) instance is associated with. | Returns: -boolean +[Firestore](./firestore_.firestore.md#firestore_class) -`true` if the objects are "equal", as defined above, or `false` otherwise. +The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. -## queryEqual() +## getFirestore() -Returns true if the provided queries point to the same collection and apply the same constraints. +Returns the existing default [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: ```typescript -export declare function queryEqual(left: Query, right: Query): boolean; +export declare function getFirestore(): Firestore; ``` +Returns: -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| left | [Query](./firestore_.query.md#query_class)<T> | A Query to compare. | -| right | [Query](./firestore_.query.md#query_class)<T> | A Query to compare. | +[Firestore](./firestore_.firestore.md#firestore_class) -Returns: +The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. -boolean +## increment() -true if the references point to the same location in the same Firestore database. +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 increment the field's current value by the given value. -## refEqual() +If either the operand or the current field value uses floating point precision, all arithmetic follows IEEE 754 semantics. If both values are integers, values outside of JavaScript's safe number range (`Number.MIN_SAFE_INTEGER` to `Number.MAX_SAFE_INTEGER`) are also subject to precision loss. Furthermore, once processed by the Firestore backend, all integer operations are capped between -2^63 and 2^63-1. -Returns true if the provided references are equal. +If the current field value is not of type `number`, or if the field does not yet exist, the transformation sets the field to the given value. Signature: ```typescript -export declare function refEqual(left: DocumentReference | CollectionReference, right: DocumentReference | CollectionReference): boolean; +export declare function increment(n: number): FieldValue; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| left | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> \| [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | A reference to compare. | -| right | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> \| [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | A reference to compare. | +| n | number | The value to increment by. | Returns: -boolean +[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) -true if the references point to the same location in the same Firestore database. +The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()` -## snapshotEqual() +## initializeFirestore() -Returns true if the provided snapshots are equal. +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). Signature: ```typescript -export declare function snapshotEqual(left: DocumentSnapshot | QuerySnapshot, right: DocumentSnapshot | QuerySnapshot): boolean; +export declare function initializeFirestore(app: FirebaseApp, settings: FirestoreSettings, databaseId?: string): Firestore; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| left | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T> \| [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T> | A snapshot to compare. | -| right | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T> \| [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T> | A snapshot to compare. | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) with which the [Firestore](./firestore_.firestore.md#firestore_class) instance will be associated. | +| settings | [FirestoreSettings](./firestore_.firestoresettings.md#firestoresettings_interface) | A settings object to configure the [Firestore](./firestore_.firestore.md#firestore_class) instance. | +| databaseId | string | The name of database. | Returns: -boolean +[Firestore](./firestore_.firestore.md#firestore_class) -true if the snapshots are equal. +A newly initialized [Firestore](./firestore_.firestore.md#firestore_class) instance. ## limit() -Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the first matching documents. +Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that only returns the first matching documents. Signature: ```typescript -export declare function limit(limit: number): QueryLimitConstraint; +export declare function limit(limit: number): QueryConstraint; ``` ### Parameters @@ -1084,20 +1003,20 @@ export declare function limit(limit: number): QueryLimitConstraint; Returns: -[QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) +[QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) -The created [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class). +The created [Query](./firestore_.query.md#query_class). ## limitToLast() -Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the last matching documents. +Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that only returns the last matching documents. You must specify at least one `orderBy` clause for `limitToLast` queries, otherwise an exception will be thrown during execution. Signature: ```typescript -export declare function limitToLast(limit: number): QueryLimitConstraint; +export declare function limitToLast(limit: number): QueryConstraint; ``` ### Parameters @@ -1108,151 +1027,171 @@ export declare function limitToLast(limit: number): QueryLimitConstraint; Returns: -[QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) +[QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) -The created [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class). +The created [Query](./firestore_.query.md#query_class). -## setLogLevel() +## loadBundle() -Sets the verbosity of Cloud Firestore logs (debug, error, or silent). +Loads a Firestore bundle into the local cache. Signature: ```typescript -export declare function setLogLevel(logLevel: LogLevel): void; +export declare function loadBundle(firestore: Firestore, bundleData: ReadableStream | ArrayBuffer | string): LoadBundleTask; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| logLevel | LogLevel | The verbosity you set for activity and error logging. Can be any of the following values:

  • debug for the most verbose logging level, primarily for debugging.
  • error to log errors only.
  • silent to turn off logging.
| +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to load bundles for. | +| bundleData | ReadableStream<Uint8Array> \| ArrayBuffer \| string | An object representing the bundle to be loaded. Valid objects are ArrayBuffer, ReadableStream<Uint8Array> or string. | Returns: -void +[LoadBundleTask](./firestore_.loadbundletask.md#loadbundletask_class) -## increment() +A `LoadBundleTask` object, which notifies callers with progress updates, and completion or error events. It can be used as a `Promise`. -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 increment the field's current value by the given value. +## namedQuery() -If either the operand or the current field value uses floating point precision, all arithmetic follows IEEE 754 semantics. If both values are integers, values outside of JavaScript's safe number range (`Number.MIN_SAFE_INTEGER` to `Number.MAX_SAFE_INTEGER`) are also subject to precision loss. Furthermore, once processed by the Firestore backend, all integer operations are capped between -2^63 and 2^63-1. +Reads a Firestore [Query](./firestore_.query.md#query_class) from local cache, identified by the given name. -If the current field value is not of type `number`, or if the field does not yet exist, the transformation sets the field to the given value. +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](./firestore_.query.md#query_class) by name. Signature: ```typescript -export declare function increment(n: number): FieldValue; +export declare function namedQuery(firestore: Firestore, name: string): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| n | number | The value to increment by. | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to read the query from. | +| name | string | The name of the query. | Returns: -[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) - -The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()` +Promise<[Query](./firestore_.query.md#query_class) \| null> -## getCountFromServer() +A `Promise` that is resolved with the Query or `null`. -Calculates the number of documents in the result set of the given query, without actually downloading the documents. +## onSnapshot() -Using this function to count the documents is efficient because only the final count, not the documents' data, is downloaded. This function can even count the documents if the result set would be prohibitively large to download entirely (e.g. thousands of documents). +Attaches a listener for `DocumentSnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. -The result received from the server is presented, unaltered, without considering any local state. That is, documents in the local cache are not taken into consideration, neither are local modifications not yet synchronized with the server. Previously-downloaded results, if any, are not used: every request using this source necessarily involves a round trip to the server. +NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. Signature: ```typescript -export declare function getCountFromServer(query: Query): Promise; -}>>; +export declare function onSnapshot(reference: DocumentReference, observer: { + next?: (snapshot: DocumentSnapshot) => void; + error?: (error: FirestoreError) => void; + complete?: () => void; +}): Unsubscribe; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| query | [Query](./firestore_.query.md#query_class)<unknown> | The query whose result set size to calculate. | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to listen to. | +| observer | { next?: (snapshot: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>) => void; error?: (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void; complete?: () => void; } | A single object containing next and error callbacks. | Returns: -Promise<[AggregateQuerySnapshot](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<{ count: [AggregateField](./firestore_.aggregatefield.md#aggregatefield_class)<number>; }>> +[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) -A Promise that will be resolved with the count; the count can be retrieved from `snapshot.data().count`, where `snapshot` is the `AggregateQuerySnapshot` to which the returned Promise resolves. +An unsubscribe function that can be called to cancel the snapshot listener. -## getDocs() +## onSnapshot() -Executes the query and returns the results as a `QuerySnapshot`. +Attaches a listener for `DocumentSnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. -Note: `getDocs()` attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. To specify this behavior, invoke [getDocsFromCache()](./firestore_.md#getdocsfromcache) or [getDocsFromServer()](./firestore_.md#getdocsfromserver). +NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. Signature: ```typescript -export declare function getDocs(query: Query): Promise>; +export declare function onSnapshot(reference: DocumentReference, options: SnapshotListenOptions, observer: { + next?: (snapshot: DocumentSnapshot) => void; + error?: (error: FirestoreError) => void; + complete?: () => void; +}): Unsubscribe; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| query | [Query](./firestore_.query.md#query_class)<T> | | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to listen to. | +| options | [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | Options controlling the listen behavior. | +| observer | { next?: (snapshot: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>) => void; error?: (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void; complete?: () => void; } | A single object containing next and error callbacks. | Returns: -Promise<[QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>> +[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) -A `Promise` that will be resolved with the results of the query. +An unsubscribe function that can be called to cancel the snapshot listener. -## getDocsFromCache() +## onSnapshot() + +Attaches a listener for `DocumentSnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. -Executes the query and returns the results as a `QuerySnapshot` from cache. Returns an empty result set if no documents matching the query are currently cached. +NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. Signature: ```typescript -export declare function getDocsFromCache(query: Query): Promise>; +export declare function onSnapshot(reference: DocumentReference, onNext: (snapshot: DocumentSnapshot) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| query | [Query](./firestore_.query.md#query_class)<T> | | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to listen to. | +| onNext | (snapshot: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>) => void | A callback to be called every time a new DocumentSnapshot is available. | +| onError | (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void | A callback to be called if the listen fails or is cancelled. No further callbacks will occur. | +| onCompletion | () => void | Can be provided, but will not be called since streams are never ending. | Returns: -Promise<[QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>> +[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) -A `Promise` that will be resolved with the results of the query. +An unsubscribe function that can be called to cancel the snapshot listener. -## getDocsFromServer() +## onSnapshot() -Executes the query and returns the results as a `QuerySnapshot` from the server. Returns an error if the network is not available. +Attaches a listener for `DocumentSnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. + +NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. Signature: ```typescript -export declare function getDocsFromServer(query: Query): Promise>; +export declare function onSnapshot(reference: DocumentReference, options: SnapshotListenOptions, onNext: (snapshot: DocumentSnapshot) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| query | [Query](./firestore_.query.md#query_class)<T> | | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to listen to. | +| options | [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | Options controlling the listen behavior. | +| onNext | (snapshot: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>) => void | A callback to be called every time a new DocumentSnapshot is available. | +| onError | (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void | A callback to be called if the listen fails or is cancelled. No further callbacks will occur. | +| onCompletion | () => void | Can be provided, but will not be called since streams are never ending. | Returns: -Promise<[QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>> +[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) -A `Promise` that will be resolved with the results of the query. +An unsubscribe function that can be called to cancel the snapshot listener. ## onSnapshot() @@ -1368,6 +1307,83 @@ export declare function onSnapshot(query: Query, options: SnapshotListenOp An unsubscribe function that can be called to cancel the snapshot listener. +## onSnapshotsInSync() + +Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners. + +NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use SnapshotMetadata in the individual listeners to determine if a snapshot is from the cache or the server. + +Signature: + +```typescript +export declare function onSnapshotsInSync(firestore: Firestore, observer: { + next?: (value: void) => void; + error?: (error: FirestoreError) => void; + complete?: () => void; +}): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The instance of Firestore for synchronizing snapshots. | +| observer | { next?: (value: void) => void; error?: (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void; complete?: () => void; } | A single object containing next and error callbacks. | + +Returns: + +[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) + +An unsubscribe function that can be called to cancel the snapshot listener. + +## onSnapshotsInSync() + +Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners. + +NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use `SnapshotMetadata` in the individual listeners to determine if a snapshot is from the cache or the server. + +Signature: + +```typescript +export declare function onSnapshotsInSync(firestore: Firestore, onSync: () => void): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The Firestore instance for synchronizing snapshots. | +| onSync | () => void | A callback to be called every time all snapshot listeners are in sync with each other. | + +Returns: + +[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) + +An unsubscribe function that can be called to cancel the snapshot listener. + +## orderBy() + +Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that sorts the query result by the specified field, optionally in descending order instead of ascending. + +Signature: + +```typescript +export declare function orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDirection): QueryConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldPath | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The field to sort by. | +| directionStr | [OrderByDirection](./firestore_.md#orderbydirection) | Optional direction to sort by ('asc' or 'desc'). If not specified, order will be ascending. | + +Returns: + +[QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) + +The created [Query](./firestore_.query.md#query_class). + ## query() Creates a new immutable instance of [Query](./firestore_.query.md#query_class) that is extended to also include additional query constraints. @@ -1393,391 +1409,368 @@ export declare function query(query: Query, ...queryConstraints: QueryCons if any of the provided query constraints cannot be combined with the existing or new constraints. -## addDoc() +## queryEqual() -Add a new document to specified `CollectionReference` with the given data, assigning it a document ID automatically. +Returns true if the provided queries point to the same collection and apply the same constraints. Signature: ```typescript -export declare function addDoc(reference: CollectionReference, data: WithFieldValue): Promise>; +export declare function queryEqual(left: Query, right: Query): boolean; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| reference | [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | A reference to the collection to add this document to. | -| data | [WithFieldValue](./firestore_.md#withfieldvalue)<T> | An Object containing the data for the new document. | +| left | [Query](./firestore_.query.md#query_class)<T> | A Query to compare. | +| right | [Query](./firestore_.query.md#query_class)<T> | A Query to compare. | Returns: -Promise<[DocumentReference](./firestore_.documentreference.md#documentreference_class)<T>> +boolean -A `Promise` resolved with a `DocumentReference` pointing to the newly created document after it has been written to the backend (Note that it won't resolve while you're offline). +true if the references point to the same location in the same Firestore database. -## collection() +## refEqual() -Gets a `CollectionReference` instance that refers to a subcollection of `reference` at the the specified relative path. +Returns true if the provided references are equal. Signature: ```typescript -export declare function collection(reference: CollectionReference, path: string, ...pathSegments: string[]): CollectionReference; +export declare function refEqual(left: DocumentReference | CollectionReference, right: DocumentReference | CollectionReference): boolean; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| reference | [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<unknown> | A reference to a collection. | -| path | string | A slash-separated path to a collection. | -| pathSegments | string\[\] | Additional path segments to apply relative to the first argument. | +| left | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> \| [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | A reference to compare. | +| right | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> \| [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | A reference to compare. | Returns: -[CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> - -The `CollectionReference` instance. +boolean -## Exceptions +true if the references point to the same location in the same Firestore database. -If the final path has an even number of segments and does not point to a collection. +## runTransaction() -## collection() +Executes the given `updateFunction` and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, Cloud Firestore retries the `updateFunction`. If it fails to commit after 5 attempts, the transaction fails. -Gets a `CollectionReference` instance that refers to a subcollection of `reference` at the the specified relative path. +The maximum number of writes allowed in a single transaction is 500. Signature: ```typescript -export declare function collection(reference: DocumentReference, path: string, ...pathSegments: string[]): CollectionReference; +export declare function runTransaction(firestore: Firestore, updateFunction: (transaction: Transaction) => Promise, options?: TransactionOptions): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class) | A reference to a Firestore document. | -| path | string | A slash-separated path to a collection. | -| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | A reference to the Firestore database to run this transaction against. | +| updateFunction | (transaction: [Transaction](./firestore_.transaction.md#transaction_class)) => Promise<T> | The function to execute within the transaction context. | +| options | [TransactionOptions](./firestore_.transactionoptions.md#transactionoptions_interface) | An options object to configure maximum number of attempts to commit. | Returns: -[CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> +Promise<T> + +If the transaction completed successfully or was explicitly aborted (the `updateFunction` returned a failed promise), the promise returned by the `updateFunction `is returned here. Otherwise, if the transaction failed, a rejected promise with the corresponding failure error is returned. + +## 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. -The `CollectionReference` instance. +Signature: -## Exceptions +```typescript +export declare function serverTimestamp(): FieldValue; +``` +Returns: -If the final path has an even number of segments and does not point to a collection. +[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) -## deleteDoc() +## setDoc() -Deletes the document referred to by the specified `DocumentReference`. +Writes to the document referred to by this `DocumentReference`. If the document does not yet exist, it will be created. Signature: ```typescript -export declare function deleteDoc(reference: DocumentReference): Promise; +export declare function setDoc(reference: DocumentReference, data: WithFieldValue): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to the document to delete. | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to write. | +| data | [WithFieldValue](./firestore_.md#withfieldvalue)<T> | A map of the fields and values for the document. | Returns: Promise<void> -A Promise resolved once the document has been successfully deleted from the backend (note that it won't resolve while you're offline). +A `Promise` resolved once the data has been successfully written to the backend (note that it won't resolve while you're offline). -## doc() +## setDoc() -Gets a `DocumentReference` instance that refers to a document within `reference` at the specified relative path. If no path is specified, an automatically-generated unique ID will be used for the returned `DocumentReference`. +Writes to the document referred to by the specified `DocumentReference`. If the document does not yet exist, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. Signature: ```typescript -export declare function doc(reference: CollectionReference, path?: string, ...pathSegments: string[]): DocumentReference; +export declare function setDoc(reference: DocumentReference, data: PartialWithFieldValue, options: SetOptions): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| reference | [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | A reference to a collection. | -| path | string | A slash-separated path to a document. Has to be omitted to use auto-genrated IDs. | -| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to write. | +| data | [PartialWithFieldValue](./firestore_.md#partialwithfieldvalue)<T> | A map of the fields and values for the document. | +| options | [SetOptions](./firestore_.md#setoptions) | An object to configure the set behavior. | Returns: -[DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> +Promise<void> -The `DocumentReference` instance. +A Promise resolved once the data has been successfully written to the backend (note that it won't resolve while you're offline). -## Exceptions +## setIndexConfiguration() -If the final path has an odd number of segments and does not point to a document. +> 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. +> -## doc() +Configures indexing for local query execution. Any previous index configuration is overridden. The `Promise` resolves once the index configuration has been persisted. -Gets a `DocumentReference` instance that refers to a document within `reference` at the specified relative path. +The index entries themselves are created asynchronously. You can continue to use queries that require indexing even if the indices are not yet available. Query execution will automatically start using the index once the index entries have been written. + +Indexes are only supported with IndexedDb persistence. Invoke either `enableIndexedDbPersistence()` or `enableMultiTabIndexedDbPersistence()` before setting an index configuration. If IndexedDb is not enabled, any index configuration is ignored. Signature: ```typescript -export declare function doc(reference: DocumentReference, path: string, ...pathSegments: string[]): DocumentReference; +export declare function setIndexConfiguration(firestore: Firestore, configuration: IndexConfiguration): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to a Firestore document. | -| path | string | A slash-separated path to a document. | -| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to configure indexes for. | +| configuration | [IndexConfiguration](./firestore_.indexconfiguration.md#indexconfiguration_interface) | The index definition. | Returns: -[DocumentReference](./firestore_.documentreference.md#documentreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> +Promise<void> -The `DocumentReference` instance. +A `Promise` that resolves once all indices are successfully configured. ## Exceptions -If the final path has an odd number of segments and does not point to a document. +FirestoreError if the JSON format is invalid. -## getDoc() +## setIndexConfiguration() -Reads the document referred to by this `DocumentReference`. +> 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. +> -Note: `getDoc()` attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. To specify this behavior, invoke [getDocFromCache()](./firestore_.md#getdocfromcache) or [getDocFromServer()](./firestore_.md#getdocfromserver). +Configures indexing for local query execution. Any previous index configuration is overridden. The `Promise` resolves once the index configuration has been persisted. + +The index entries themselves are created asynchronously. You can continue to use queries that require indexing even if the indices are not yet available. Query execution will automatically start using the index once the index entries have been written. + +Indexes are only supported with IndexedDb persistence. Invoke either `enableIndexedDbPersistence()` or `enableMultiTabIndexedDbPersistence()` before setting an index configuration. If IndexedDb is not enabled, any index configuration is ignored. + +The method accepts the JSON format exported by the Firebase CLI (`firebase firestore:indexes`). If the JSON format is invalid, this method throws an error. Signature: ```typescript -export declare function getDoc(reference: DocumentReference): Promise>; +export declare function setIndexConfiguration(firestore: Firestore, json: string): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | The reference of the document to fetch. | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to configure indexes for. | +| json | string | The JSON format exported by the Firebase CLI. | Returns: -Promise<[DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>> +Promise<void> -A Promise resolved with a `DocumentSnapshot` containing the current document contents. +A `Promise` that resolves once all indices are successfully configured. -## getDocFromCache() +## Exceptions -Reads the document referred to by this `DocumentReference` from cache. Returns an error if the document is not currently cached. +FirestoreError if the JSON format is invalid. + +## setLogLevel() + +Sets the verbosity of Cloud Firestore logs (debug, error, or silent). Signature: ```typescript -export declare function getDocFromCache(reference: DocumentReference): Promise>; +export declare function setLogLevel(logLevel: LogLevel): void; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | | +| logLevel | LogLevel | The verbosity you set for activity and error logging. Can be any of the following values:
  • debug for the most verbose logging level, primarily for debugging.
  • error to log errors only.
  • silent to turn off logging.
| Returns: -Promise<[DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>> - -A `Promise` resolved with a `DocumentSnapshot` containing the current document contents. +void -## getDocFromServer() +## snapshotEqual() -Reads the document referred to by this `DocumentReference` from the server. Returns an error if the network is not available. +Returns true if the provided snapshots are equal. Signature: ```typescript -export declare function getDocFromServer(reference: DocumentReference): Promise>; +export declare function snapshotEqual(left: DocumentSnapshot | QuerySnapshot, right: DocumentSnapshot | QuerySnapshot): boolean; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | | +| left | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T> \| [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T> | A snapshot to compare. | +| right | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T> \| [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T> | A snapshot to compare. | Returns: -Promise<[DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>> - -A `Promise` resolved with a `DocumentSnapshot` containing the current document contents. +boolean -## onSnapshot() +true if the snapshots are equal. -Attaches a listener for `DocumentSnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. +## startAfter() -NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. +Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. Signature: ```typescript -export declare function onSnapshot(reference: DocumentReference, observer: { - next?: (snapshot: DocumentSnapshot) => void; - error?: (error: FirestoreError) => void; - complete?: () => void; -}): Unsubscribe; +export declare function startAfter(snapshot: DocumentSnapshot): QueryConstraint; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to listen to. | -| observer | { next?: (snapshot: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>) => void; error?: (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void; complete?: () => void; } | A single object containing next and error callbacks. | +| snapshot | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to start after. | Returns: -[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) - -An unsubscribe function that can be called to cancel the snapshot listener. +[QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) -## onSnapshot() +A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()` -Attaches a listener for `DocumentSnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. +## startAfter() -NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. +Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. Signature: ```typescript -export declare function onSnapshot(reference: DocumentReference, options: SnapshotListenOptions, observer: { - next?: (snapshot: DocumentSnapshot) => void; - error?: (error: FirestoreError) => void; - complete?: () => void; -}): Unsubscribe; +export declare function startAfter(...fieldValues: unknown[]): QueryConstraint; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to listen to. | -| options | [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | Options controlling the listen behavior. | -| observer | { next?: (snapshot: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>) => void; error?: (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void; complete?: () => void; } | A single object containing next and error callbacks. | +| fieldValues | unknown\[\] | The field values to start this query after, in order of the query's order by. | Returns: -[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) - -An unsubscribe function that can be called to cancel the snapshot listener. +[QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) -## onSnapshot() +A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()` -Attaches a listener for `DocumentSnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. +## startAt() -NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. +Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the `orderBy` of this query. Signature: ```typescript -export declare function onSnapshot(reference: DocumentReference, onNext: (snapshot: DocumentSnapshot) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe; +export declare function startAt(snapshot: DocumentSnapshot): QueryConstraint; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to listen to. | -| onNext | (snapshot: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>) => void | A callback to be called every time a new DocumentSnapshot is available. | -| onError | (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void | A callback to be called if the listen fails or is cancelled. No further callbacks will occur. | -| onCompletion | () => void | Can be provided, but will not be called since streams are never ending. | +| snapshot | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to start at. | Returns: -[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) - -An unsubscribe function that can be called to cancel the snapshot listener. +[QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) -## onSnapshot() +A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()`. -Attaches a listener for `DocumentSnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. +## startAt() -NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. +Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. Signature: ```typescript -export declare function onSnapshot(reference: DocumentReference, options: SnapshotListenOptions, onNext: (snapshot: DocumentSnapshot) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe; +export declare function startAt(...fieldValues: unknown[]): QueryConstraint; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to listen to. | -| options | [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | Options controlling the listen behavior. | -| onNext | (snapshot: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>) => void | A callback to be called every time a new DocumentSnapshot is available. | -| onError | (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void | A callback to be called if the listen fails or is cancelled. No further callbacks will occur. | -| onCompletion | () => void | Can be provided, but will not be called since streams are never ending. | +| fieldValues | unknown\[\] | The field values to start this query at, in order of the query's order by. | Returns: -[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) - -An unsubscribe function that can be called to cancel the snapshot listener. - -## setDoc() - -Writes to the document referred to by this `DocumentReference`. If the document does not yet exist, it will be created. - -Signature: - -```typescript -export declare function setDoc(reference: DocumentReference, data: WithFieldValue): Promise; -``` +[QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) -### Parameters +A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()`. -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to write. | -| data | [WithFieldValue](./firestore_.md#withfieldvalue)<T> | A map of the fields and values for the document. | +## terminate() -Returns: +Terminates the provided [Firestore](./firestore_.firestore.md#firestore_class) instance. -Promise<void> +After calling `terminate()` only the `clearIndexedDbPersistence()` function may be used. Any other function will throw a `FirestoreError`. -A `Promise` resolved once the data has been successfully written to the backend (note that it won't resolve while you're offline). +To restart after termination, create a new instance of FirebaseFirestore with [getFirestore()](./firestore_.md#getfirestore). -## setDoc() +Termination does not cancel any pending writes, and any promises that are awaiting a response from the server will not be resolved. If you have persistence enabled, the next time you start this instance, it will resume sending these writes to the server. -Writes to the document referred to by the specified `DocumentReference`. If the document does not yet exist, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. +Note: Under normal circumstances, calling `terminate()` is not required. This function is useful only when you want to force this instance to release all of its resources or in combination with `clearIndexedDbPersistence()` to ensure that all local state is destroyed between test runs. Signature: ```typescript -export declare function setDoc(reference: DocumentReference, data: PartialWithFieldValue, options: SetOptions): Promise; +export declare function terminate(firestore: Firestore): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to write. | -| data | [PartialWithFieldValue](./firestore_.md#partialwithfieldvalue)<T> | A map of the fields and values for the document. | -| options | [SetOptions](./firestore_.md#setoptions) | An object to configure the set behavior. | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | Returns: Promise<void> -A Promise resolved once the data has been successfully written to the backend (note that it won't resolve while you're offline). +A `Promise` that is resolved when the instance has been successfully terminated. ## updateDoc() @@ -1829,93 +1822,79 @@ Promise<void> A `Promise` resolved once the data has been successfully written to the backend (note that it won't resolve while you're offline). -## endAt() - -Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided document (inclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. - -Signature: - -```typescript -export declare function endAt(snapshot: DocumentSnapshot): QueryEndAtConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| snapshot | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to end at. | - -Returns: - -[QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) +## waitForPendingWrites() -A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` +Waits until all currently pending writes for the active user have been acknowledged by the backend. -## endBefore() +The returned promise resolves immediately if there are no outstanding writes. Otherwise, the promise waits for all previously issued writes (including those written in a previous app session), but it does not wait for writes that were added after the function is called. If you want to wait for additional writes, call `waitForPendingWrites()` again. -Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. +Any outstanding `waitForPendingWrites()` promises are rejected during user changes. Signature: ```typescript -export declare function endBefore(snapshot: DocumentSnapshot): QueryEndAtConstraint; +export declare function waitForPendingWrites(firestore: Firestore): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| snapshot | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to end before. | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | Returns: -[QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) +Promise<void> -A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` +A `Promise` which resolves when all currently pending writes have been acknowledged by the backend. -## startAfter() +## where() -Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. +Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that enforces that documents must contain the specified field and that the value should satisfy the relation constraint provided. Signature: ```typescript -export declare function startAfter(snapshot: DocumentSnapshot): QueryStartAtConstraint; +export declare function where(fieldPath: string | FieldPath, opStr: WhereFilterOp, value: unknown): QueryConstraint; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| snapshot | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to start after. | +| fieldPath | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The path to compare | +| opStr | [WhereFilterOp](./firestore_.md#wherefilterop) | The operation string (e.g "&lt;", "&lt;=", "==", "&lt;", "&lt;=", "!="). | +| value | unknown | The value for comparison | Returns: -[QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) +[QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) -A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()` +The created [Query](./firestore_.query.md#query_class). -## startAt() +## writeBatch() + +Creates a write batch, used for performing multiple writes as a single atomic operation. The maximum number of writes allowed in a single [WriteBatch](./firestore_.writebatch.md#writebatch_class) is 500. -Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the `orderBy` of this query. +Unlike transactions, write batches are persisted offline and therefore are preferable when you don't need to condition your writes on read data. Signature: ```typescript -export declare function startAt(snapshot: DocumentSnapshot): QueryStartAtConstraint; +export declare function writeBatch(firestore: Firestore): WriteBatch; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| snapshot | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to start at. | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | Returns: -[QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) +[WriteBatch](./firestore_.writebatch.md#writebatch_class) -A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()`. +A [WriteBatch](./firestore_.writebatch.md#writebatch_class) that can be used to atomically execute multiple writes. ## CACHE\_SIZE\_UNLIMITED @@ -2051,16 +2030,6 @@ Describes the different query constraints available in this SDK. export declare type QueryConstraintType = 'where' | 'orderBy' | 'limit' | 'limitToLast' | 'startAt' | 'startAfter' | 'endAt' | 'endBefore'; ``` -## QueryNonFilterConstraint - -`QueryNonFilterConstraint` is a helper union type that represents QueryConstraints which are used to narrow or order the set of documents, but that do not explicitly filter on a document field. `QueryNonFilterConstraint`s are created by invoking [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains the `QueryConstraint`. - -Signature: - -```typescript -export declare type QueryNonFilterConstraint = QueryOrderByConstraint | QueryLimitConstraint | QueryStartAtConstraint | QueryEndAtConstraint; -``` - ## SetOptions An options object that configures the behavior of [setDoc()](./firestore_lite.md#setdoc), and calls. These calls can be configured to perform granular merges instead of overwriting the target documents in their entirety by providing a `SetOptions` with `merge: true`. diff --git a/docs-devsite/firestore_.queryconstraint.md b/docs-devsite/firestore_.queryconstraint.md index 77ebddf1c65..eb7a4fca906 100644 --- a/docs-devsite/firestore_.queryconstraint.md +++ b/docs-devsite/firestore_.queryconstraint.md @@ -10,7 +10,7 @@ https://github.com/firebase/firebase-js-sdk {% endcomment %} # QueryConstraint class -A `QueryConstraint` is used to narrow the set of documents returned by a Firestore query. `QueryConstraint`s are created by invoking [where()](./firestore_.md#where), [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit), [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryConstraint`. +A `QueryConstraint` is used to narrow the set of documents returned by a Firestore query. `QueryConstraint`s are created by invoking [where()](./firestore_.md#where), [orderBy()](./firestore_.md#orderby), [startAt()](./firestore_.md#startat), [startAfter()](./firestore_.md#startafter), , [endAt()](./firestore_.md#endat), [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryConstraint`. Signature: @@ -22,11 +22,11 @@ export declare abstract class QueryConstraint | Property | Modifiers | Type | Description | | --- | --- | --- | --- | -| [type](./firestore_.queryconstraint.md#queryconstrainttype) | | [QueryConstraintType](./firestore_.md#queryconstrainttype) | The type of this query constraint | +| [type](./firestore_.queryconstraint.md#queryconstrainttype) | | [QueryConstraintType](./firestore_.md#queryconstrainttype) | The type of this query constraints | ## QueryConstraint.type -The type of this query constraint +The type of this query constraints Signature: diff --git a/docs-devsite/firestore_lite.md b/docs-devsite/firestore_lite.md index 3754cda22b7..e3f3653e61b 100644 --- a/docs-devsite/firestore_lite.md +++ b/docs-devsite/firestore_lite.md @@ -15,66 +15,53 @@ https://github.com/firebase/firebase-js-sdk | Function | Description | | --- | --- | -| function(app...) | -| [getFirestore(app)](./firestore_lite.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. | -| [initializeFirestore(app, settings)](./firestore_lite.md#initializefirestore) | Initializes a new instance of Cloud Firestore with the provided settings. Can only be called before any other functions, including [getFirestore()](./firestore_.md#getfirestore). If the custom settings are empty, this function is equivalent to calling [getFirestore()](./firestore_.md#getfirestore). | -| function(firestore...) | -| [collection(firestore, path, pathSegments)](./firestore_lite.md#collection) | Gets a CollectionReference instance that refers to the collection at the specified absolute path. | -| [collectionGroup(firestore, collectionId)](./firestore_lite.md#collectiongroup) | Creates and returns a new Query instance that includes all documents in the database that are contained in a collection or subcollection with the given collectionId. | -| [connectFirestoreEmulator(firestore, host, port, options)](./firestore_lite.md#connectfirestoreemulator) | Modify this instance to communicate with the Cloud Firestore emulator.Note: This must be called before this instance has been used to do any operations. | -| [doc(firestore, path, pathSegments)](./firestore_lite.md#doc) | Gets a DocumentReference instance that refers to the document at the specified absolute path. | -| [runTransaction(firestore, updateFunction, options)](./firestore_lite.md#runtransaction) | Executes the given updateFunction and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, Cloud Firestore retries the updateFunction. If it fails to commit after 5 attempts, the transaction fails.The maximum number of writes allowed in a single transaction is 500. | -| [terminate(firestore)](./firestore_lite.md#terminate) | Terminates the provided Firestore instance.After calling terminate() only the clearIndexedDbPersistence() functions may be used. Any other function will throw a FirestoreError. Termination does not cancel any pending writes, and any promises that are awaiting a response from the server will not be resolved.To restart after termination, create a new instance of Firestore with [getFirestore()](./firestore_.md#getfirestore).Note: Under normal circumstances, calling terminate() is not required. This function is useful only when you want to force this instance to release all of its resources or in combination with [clearIndexedDbPersistence()](./firestore_.md#clearindexeddbpersistence) to ensure that all local state is destroyed between test runs. | -| [writeBatch(firestore)](./firestore_lite.md#writebatch) | Creates a write batch, used for performing multiple writes as a single atomic operation. The maximum number of writes allowed in a single WriteBatch is 500.The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | -| function() | -| [deleteField()](./firestore_lite.md#deletefield) | Returns a sentinel for use with [updateDoc()](./firestore_lite.md#updatedoc) or [setDoc()](./firestore_lite.md#setdoc) with {merge: true} to mark a field for deletion. | -| [documentId()](./firestore_lite.md#documentid) | Returns a special sentinel FieldPath to refer to the ID of a document. It can be used in queries to sort or filter by the document ID. | -| [getFirestore()](./firestore_lite.md#getfirestore) | Returns the existing default [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. | -| [serverTimestamp()](./firestore_lite.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(elements...) | +| [addDoc(reference, data)](./firestore_lite.md#adddoc) | Add a new document to specified CollectionReference with the given data, assigning it a document ID automatically.The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | +| [aggregateQuerySnapshotEqual(left, right)](./firestore_lite.md#aggregatequerysnapshotequal) | Compares two AggregateQuerySnapshot instances for equality.Two AggregateQuerySnapshot instances are considered "equal" if they have underlying queries that compare equal, and the same data. | | [arrayRemove(elements)](./firestore_lite.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_lite.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. | -| function(fieldPath...) | -| [orderBy(fieldPath, directionStr)](./firestore_lite.md#orderby) | Creates a [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class) that sorts the query result by the specified field, optionally in descending order instead of ascending.Note: Documents that do not contain the specified field will not be present in the query result. | -| [where(fieldPath, opStr, value)](./firestore_lite.md#where) | Creates a [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) that enforces that documents must contain the specified field and that the value should satisfy the relation constraint provided. | -| function(fieldValues...) | -| [endAt(fieldValues)](./firestore_lite.md#endat) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | -| [endBefore(fieldValues)](./firestore_lite.md#endbefore) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | -| [startAfter(fieldValues)](./firestore_lite.md#startafter) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | -| [startAt(fieldValues)](./firestore_lite.md#startat) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | -| function(left...) | -| [aggregateQuerySnapshotEqual(left, right)](./firestore_lite.md#aggregatequerysnapshotequal) | Compares two AggregateQuerySnapshot instances for equality.Two AggregateQuerySnapshot instances are considered "equal" if they have underlying queries that compare equal, and the same data. | -| [queryEqual(left, right)](./firestore_lite.md#queryequal) | Returns true if the provided queries point to the same collection and apply the same constraints. | -| [refEqual(left, right)](./firestore_lite.md#refequal) | Returns true if the provided references are equal. | -| [snapshotEqual(left, right)](./firestore_lite.md#snapshotequal) | Returns true if the provided snapshots are equal. | -| function(limit...) | -| [limit(limit)](./firestore_lite.md#limit) | Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the first matching documents. | -| [limitToLast(limit)](./firestore_lite.md#limittolast) | Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the last matching documents.You must specify at least one orderBy clause for limitToLast queries, otherwise an exception will be thrown during execution. | -| function(logLevel...) | -| [setLogLevel(logLevel)](./firestore_lite.md#setloglevel) | Sets the verbosity of Cloud Firestore logs (debug, error, or silent). | -| function(n...) | -| [increment(n)](./firestore_lite.md#increment) | 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 increment the field's current value by the given value.If either the operand or the current field value uses floating point precision, all arithmetic follows IEEE 754 semantics. If both values are integers, values outside of JavaScript's safe number range (Number.MIN_SAFE_INTEGER to Number.MAX_SAFE_INTEGER) are also subject to precision loss. Furthermore, once processed by the Firestore backend, all integer operations are capped between -2^63 and 2^63-1.If the current field value is not of type number, or if the field does not yet exist, the transformation sets the field to the given value. | -| function(query...) | -| [getCount(query)](./firestore_lite.md#getcount) | Calculates the number of documents in the result set of the given query, without actually downloading the documents.Using this function to count the documents is efficient because only the final count, not the documents' data, is downloaded. This function can even count the documents if the result set would be prohibitively large to download entirely (e.g. thousands of documents). | -| [getDocs(query)](./firestore_lite.md#getdocs) | Executes the query and returns the results as a [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class).All queries are executed directly by the server, even if the the query was previously executed. Recent modifications are only reflected in the retrieved results if they have already been applied by the backend. If the client is offline, the operation fails. To see previously cached result and local modifications, use the full Firestore SDK. | -| [query(query, queryConstraints)](./firestore_lite.md#query) | Creates a new immutable instance of [Query](./firestore_.query.md#query_class) that is extended to also include additional query constraints. | -| function(reference...) | -| [addDoc(reference, data)](./firestore_lite.md#adddoc) | Add a new document to specified CollectionReference with the given data, assigning it a document ID automatically.The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | +| [collection(firestore, path, pathSegments)](./firestore_lite.md#collection) | Gets a CollectionReference instance that refers to the collection at the specified absolute path. | | [collection(reference, path, pathSegments)](./firestore_lite.md#collection) | Gets a CollectionReference instance that refers to a subcollection of reference at the the specified relative path. | | [collection(reference, path, pathSegments)](./firestore_lite.md#collection) | Gets a CollectionReference instance that refers to a subcollection of reference at the the specified relative path. | +| [collectionGroup(firestore, collectionId)](./firestore_lite.md#collectiongroup) | Creates and returns a new Query instance that includes all documents in the database that are contained in a collection or subcollection with the given collectionId. | +| [connectFirestoreEmulator(firestore, host, port, options)](./firestore_lite.md#connectfirestoreemulator) | Modify this instance to communicate with the Cloud Firestore emulator.Note: This must be called before this instance has been used to do any operations. | | [deleteDoc(reference)](./firestore_lite.md#deletedoc) | Deletes the document referred to by the specified DocumentReference.The deletion will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the delete fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | +| [deleteField()](./firestore_lite.md#deletefield) | Returns a sentinel for use with [updateDoc()](./firestore_lite.md#updatedoc) or [setDoc()](./firestore_lite.md#setdoc) with {merge: true} to mark a field for deletion. | +| [doc(firestore, path, pathSegments)](./firestore_lite.md#doc) | Gets a DocumentReference instance that refers to the document at the specified absolute path. | | [doc(reference, path, pathSegments)](./firestore_lite.md#doc) | Gets a DocumentReference instance that refers to a document within reference at the specified relative path. If no path is specified, an automatically-generated unique ID will be used for the returned DocumentReference. | | [doc(reference, path, pathSegments)](./firestore_lite.md#doc) | Gets a DocumentReference instance that refers to a document within reference at the specified relative path. | +| [documentId()](./firestore_lite.md#documentid) | Returns a special sentinel FieldPath to refer to the ID of a document. It can be used in queries to sort or filter by the document ID. | +| [endAt(snapshot)](./firestore_lite.md#endat) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end at the provided document (inclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | +| [endAt(fieldValues)](./firestore_lite.md#endat) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | +| [endBefore(snapshot)](./firestore_lite.md#endbefore) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | +| [endBefore(fieldValues)](./firestore_lite.md#endbefore) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | +| [getCount(query)](./firestore_lite.md#getcount) | Calculates the number of documents in the result set of the given query, without actually downloading the documents.Using this function to count the documents is efficient because only the final count, not the documents' data, is downloaded. This function can even count the documents if the result set would be prohibitively large to download entirely (e.g. thousands of documents). | | [getDoc(reference)](./firestore_lite.md#getdoc) | Reads the document referred to by the specified document reference.All documents are directly fetched from the server, even if the document was previously read or modified. Recent modifications are only reflected in the retrieved DocumentSnapshot if they have already been applied by the backend. If the client is offline, the read fails. If you like to use caching or see local modifications, please use the full Firestore SDK. | +| [getDocs(query)](./firestore_lite.md#getdocs) | Executes the query and returns the results as a [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class).All queries are executed directly by the server, even if the the query was previously executed. Recent modifications are only reflected in the retrieved results if they have already been applied by the backend. If the client is offline, the operation fails. To see previously cached result and local modifications, use the full Firestore SDK. | +| [getFirestore()](./firestore_lite.md#getfirestore) | Returns the existing default [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(app)](./firestore_lite.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. | +| [increment(n)](./firestore_lite.md#increment) | 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 increment the field's current value by the given value.If either the operand or the current field value uses floating point precision, all arithmetic follows IEEE 754 semantics. If both values are integers, values outside of JavaScript's safe number range (Number.MIN_SAFE_INTEGER to Number.MAX_SAFE_INTEGER) are also subject to precision loss. Furthermore, once processed by the Firestore backend, all integer operations are capped between -2^63 and 2^63-1.If the current field value is not of type number, or if the field does not yet exist, the transformation sets the field to the given value. | +| [initializeFirestore(app, settings)](./firestore_lite.md#initializefirestore) | Initializes a new instance of Cloud Firestore with the provided settings. Can only be called before any other functions, including [getFirestore()](./firestore_.md#getfirestore). If the custom settings are empty, this function is equivalent to calling [getFirestore()](./firestore_.md#getfirestore). | +| [limit(limit)](./firestore_lite.md#limit) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that only returns the first matching documents. | +| [limitToLast(limit)](./firestore_lite.md#limittolast) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that only returns the last matching documents.You must specify at least one orderBy clause for limitToLast queries, otherwise an exception will be thrown during execution. | +| [orderBy(fieldPath, directionStr)](./firestore_lite.md#orderby) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that sorts the query result by the specified field, optionally in descending order instead of ascending. | +| [query(query, queryConstraints)](./firestore_lite.md#query) | Creates a new immutable instance of [Query](./firestore_.query.md#query_class) that is extended to also include additional query constraints. | +| [queryEqual(left, right)](./firestore_lite.md#queryequal) | Returns true if the provided queries point to the same collection and apply the same constraints. | +| [refEqual(left, right)](./firestore_lite.md#refequal) | Returns true if the provided references are equal. | +| [runTransaction(firestore, updateFunction, options)](./firestore_lite.md#runtransaction) | Executes the given updateFunction and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, Cloud Firestore retries the updateFunction. If it fails to commit after 5 attempts, the transaction fails.The maximum number of writes allowed in a single transaction is 500. | +| [serverTimestamp()](./firestore_lite.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. | | [setDoc(reference, data)](./firestore_lite.md#setdoc) | Writes to the document referred to by the specified DocumentReference. If the document does not yet exist, it will be created.The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | | [setDoc(reference, data, options)](./firestore_lite.md#setdoc) | Writes to the document referred to by the specified DocumentReference. If the document does not yet exist, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document.The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | +| [setLogLevel(logLevel)](./firestore_lite.md#setloglevel) | Sets the verbosity of Cloud Firestore logs (debug, error, or silent). | +| [snapshotEqual(left, right)](./firestore_lite.md#snapshotequal) | Returns true if the provided snapshots are equal. | +| [startAfter(snapshot)](./firestore_lite.md#startafter) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | +| [startAfter(fieldValues)](./firestore_lite.md#startafter) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | +| [startAt(snapshot)](./firestore_lite.md#startat) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of this query. | +| [startAt(fieldValues)](./firestore_lite.md#startat) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | +| [terminate(firestore)](./firestore_lite.md#terminate) | Terminates the provided Firestore instance.After calling terminate() only the clearIndexedDbPersistence() functions may be used. Any other function will throw a FirestoreError. Termination does not cancel any pending writes, and any promises that are awaiting a response from the server will not be resolved.To restart after termination, create a new instance of Firestore with [getFirestore()](./firestore_.md#getfirestore).Note: Under normal circumstances, calling terminate() is not required. This function is useful only when you want to force this instance to release all of its resources or in combination with [clearIndexedDbPersistence()](./firestore_.md#clearindexeddbpersistence) to ensure that all local state is destroyed between test runs. | | [updateDoc(reference, data)](./firestore_lite.md#updatedoc) | Updates fields in the document referred to by the specified DocumentReference. The update will fail if applied to a document that does not exist.The result of this update will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the update fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | | [updateDoc(reference, field, value, moreFieldsAndValues)](./firestore_lite.md#updatedoc) | Updates fields in the document referred to by the specified DocumentReference The update will fail if applied to a document that does not exist.Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects.The result of this update will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the update fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | -| function(snapshot...) | -| [endAt(snapshot)](./firestore_lite.md#endat) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided document (inclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | -| [endBefore(snapshot)](./firestore_lite.md#endbefore) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | -| [startAfter(snapshot)](./firestore_lite.md#startafter) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | -| [startAt(snapshot)](./firestore_lite.md#startat) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of this query. | +| [where(fieldPath, opStr, value)](./firestore_lite.md#where) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that enforces that documents must contain the specified field and that the value should satisfy the relation constraint provided. | +| [writeBatch(firestore)](./firestore_lite.md#writebatch) | Creates a write batch, used for performing multiple writes as a single atomic operation. The maximum number of writes allowed in a single WriteBatch is 500.The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | ## Classes @@ -92,14 +79,9 @@ https://github.com/firebase/firebase-js-sdk | [FirestoreError](./firestore_lite.firestoreerror.md#firestoreerror_class) | An error returned by a Firestore operation. | | [GeoPoint](./firestore_lite.geopoint.md#geopoint_class) | An immutable object representing a geographic location in Firestore. The location is represented as latitude/longitude pair.Latitude values are in the range of \[-90, 90\]. Longitude values are in the range of \[-180, 180\]. | | [Query](./firestore_lite.query.md#query_class) | A Query refers to a query which you can read or listen to. You can also construct refined Query objects by adding filters and ordering. | -| [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) | A QueryConstraint is used to narrow the set of documents returned by a Firestore query. QueryConstraints are created by invoking [where()](./firestore_.md#where), [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit), [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryConstraint. | +| [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) | A QueryConstraint is used to narrow the set of documents returned by a Firestore query. QueryConstraints are created by invoking [where()](./firestore_.md#where), [orderBy()](./firestore_.md#orderby), [startAt()](./firestore_.md#startat), [startAfter()](./firestore_.md#startafter), , [endAt()](./firestore_.md#endat), [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryConstraint. | | [QueryDocumentSnapshot](./firestore_lite.querydocumentsnapshot.md#querydocumentsnapshot_class) | A QueryDocumentSnapshot contains data read from a document in your Firestore database as part of a query. The document is guaranteed to exist and its data can be extracted with .data() or .get(<field>) to get a specific field.A QueryDocumentSnapshot offers the same API surface as a DocumentSnapshot. Since query results contain only existing documents, the exists property will always be true and data() will never return 'undefined'. | -| [QueryEndAtConstraint](./firestore_lite.queryendatconstraint.md#queryendatconstraint_class) | A QueryEndAtConstraint is used to exclude documents from the end of a result set returned by a Firestore query. QueryEndAtConstraints are created by invoking [endAt()](./firestore_.md#endat) or [endBefore()](./firestore_.md#endbefore) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryEndAtConstraint. | -| [QueryFieldFilterConstraint](./firestore_lite.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) | A QueryFieldFilterConstraint is used to narrow the set of documents returned by a Firestore query by filtering on one or more document fields. QueryFieldFilterConstraints are created by invoking [where()](./firestore_.md#where) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryFieldFilterConstraint. | -| [QueryLimitConstraint](./firestore_lite.querylimitconstraint.md#querylimitconstraint_class) | A QueryLimitConstraint is used to limit the number of documents returned by a Firestore query. QueryLimitConstraints are created by invoking [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryLimitConstraint. | -| [QueryOrderByConstraint](./firestore_lite.queryorderbyconstraint.md#queryorderbyconstraint_class) | A QueryOrderByConstraint is used to sort the set of documents returned by a Firestore query. QueryOrderByConstraints are created by invoking [orderBy()](./firestore_.md#orderby) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryOrderByConstraint.Note: Documents that do not contain the orderBy field will not be present in the query result. | | [QuerySnapshot](./firestore_lite.querysnapshot.md#querysnapshot_class) | A QuerySnapshot contains zero or more DocumentSnapshot objects representing the results of a query. The documents can be accessed as an array via the docs property or enumerated using the forEach method. The number of documents can be determined via the empty and size properties. | -| [QueryStartAtConstraint](./firestore_lite.querystartatconstraint.md#querystartatconstraint_class) | A QueryStartAtConstraint is used to exclude documents from the start of a result set returned by a Firestore query. QueryStartAtConstraints are created by invoking [startAt()](./firestore_.md#startat) or [startAfter()](./firestore_.md#startafter) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryStartAtConstraint. | | [Timestamp](./firestore_lite.timestamp.md#timestamp_class) | A Timestamp represents a point in time independent of any time zone or calendar, represented as seconds and fractions of seconds at nanosecond resolution in UTC Epoch time.It is encoded using the Proleptic Gregorian Calendar which extends the Gregorian calendar backwards to year one. It is encoded assuming all minutes are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.For examples and further specifications, refer to the [Timestamp definition](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto). | | [Transaction](./firestore_lite.transaction.md#transaction_class) | A reference to a transaction.The Transaction object passed to a transaction's updateFunction provides the methods to read and write data within the transaction context. See [runTransaction()](./firestore_.md#runtransaction). | | [WriteBatch](./firestore_lite.writebatch.md#writebatch_class) | A write batch, used to perform multiple writes as a single atomic unit.A WriteBatch object can be acquired by calling [writeBatch()](./firestore_.md#writebatch). It provides methods for adding writes to the write batch. None of the writes will be committed (or visible locally) until [WriteBatch.commit()](./firestore_.writebatch.md#writebatchcommit) is called. | @@ -128,419 +110,452 @@ https://github.com/firebase/firebase-js-sdk | [PartialWithFieldValue](./firestore_lite.md#partialwithfieldvalue) | Similar to Typescript's Partial<T>, but allows nested fields to be omitted and FieldValues to be passed in as property values. | | [Primitive](./firestore_lite.md#primitive) | Primitive types. | | [QueryConstraintType](./firestore_lite.md#queryconstrainttype) | Describes the different query constraints available in this SDK. | -| [QueryNonFilterConstraint](./firestore_lite.md#querynonfilterconstraint) | QueryNonFilterConstraint is a helper union type that represents QueryConstraints which are used to narrow or order the set of documents, but that do not explicitly filter on a document field. QueryNonFilterConstraints are created by invoking [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains the QueryConstraint. | | [SetOptions](./firestore_lite.md#setoptions) | An options object that configures the behavior of [setDoc()](./firestore_lite.md#setdoc), and calls. These calls can be configured to perform granular merges instead of overwriting the target documents in their entirety by providing a SetOptions with merge: true. | | [UnionToIntersection](./firestore_lite.md#uniontointersection) | Given a union type U = T1 | T2 | ..., returns an intersected type (T1 & T2 & ...).Uses distributive conditional types and inference from conditional types. This works because multiple candidates for the same type variable in contra-variant positions causes an intersection type to be inferred. https://www.typescriptlang.org/docs/handbook/advanced-types.html\#type-inference-in-conditional-types https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection-type | | [UpdateData](./firestore_lite.md#updatedata) | Update data (for use with [updateDoc()](./firestore_.md#updatedoc)) that consists of field paths (e.g. 'foo' or 'foo.baz') mapped to values. Fields that contain dots reference nested fields within the document. FieldValues can be passed in as property values. | | [WhereFilterOp](./firestore_lite.md#wherefilterop) | Filter conditions in a [where()](./firestore_.md#where) clause are specified using the strings '&lt;', '&lt;=', '==', '!=', '&gt;=', '&gt;', 'array-contains', 'in', 'array-contains-any', and 'not-in'. | | [WithFieldValue](./firestore_lite.md#withfieldvalue) | Allows FieldValues to be passed in as a property value while maintaining type safety. | -## getFirestore() +## addDoc() -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. +Add a new document to specified `CollectionReference` with the given data, assigning it a document ID automatically. + +The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. Signature: ```typescript -export declare function getFirestore(app: FirebaseApp): Firestore; +export declare function addDoc(reference: CollectionReference, data: WithFieldValue): Promise>; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance that the returned [Firestore](./firestore_.firestore.md#firestore_class) instance is associated with. | +| reference | [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | A reference to the collection to add this document to. | +| data | [WithFieldValue](./firestore_lite.md#withfieldvalue)<T> | An Object containing the data for the new document. | Returns: -[Firestore](./firestore_lite.firestore.md#firestore_class) +Promise<[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T>> -The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. +A `Promise` resolved with a `DocumentReference` pointing to the newly created document after it has been written to the backend. -## initializeFirestore() +## Exceptions -Initializes a new instance of Cloud Firestore with the provided settings. Can only be called before any other functions, including [getFirestore()](./firestore_.md#getfirestore). If the custom settings are empty, this function is equivalent to calling [getFirestore()](./firestore_.md#getfirestore). +Error - If the provided input is not a valid Firestore document. + +## aggregateQuerySnapshotEqual() + +Compares two `AggregateQuerySnapshot` instances for equality. + +Two `AggregateQuerySnapshot` instances are considered "equal" if they have underlying queries that compare equal, and the same data. Signature: ```typescript -export declare function initializeFirestore(app: FirebaseApp, settings: Settings): Firestore; +export declare function aggregateQuerySnapshotEqual(left: AggregateQuerySnapshot, right: AggregateQuerySnapshot): boolean; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) with which the Firestore instance will be associated. | -| settings | [Settings](./firestore_lite.settings.md#settings_interface) | A settings object to configure the Firestore instance. | +| left | [AggregateQuerySnapshot](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<T> | The first AggregateQuerySnapshot to compare. | +| right | [AggregateQuerySnapshot](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<T> | The second AggregateQuerySnapshot to compare. | Returns: -[Firestore](./firestore_lite.firestore.md#firestore_class) +boolean -A newly initialized `Firestore` instance. +`true` if the objects are "equal", as defined above, or `false` otherwise. -## collection() +## arrayRemove() -Gets a `CollectionReference` instance that refers to the collection at the specified absolute path. +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. Signature: ```typescript -export declare function collection(firestore: Firestore, path: string, ...pathSegments: string[]): CollectionReference; +export declare function arrayRemove(...elements: unknown[]): FieldValue; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | A reference to the root Firestore instance. | -| path | string | A slash-separated path to a collection. | -| pathSegments | string\[\] | Additional path segments to apply relative to the first argument. | +| elements | unknown\[\] | The elements to remove from the array. | Returns: -[CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> - -The `CollectionReference` instance. - -## Exceptions +[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) -If the final path has an even number of segments and does not point to a collection. +The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()` -## collectionGroup() +## arrayUnion() -Creates and returns a new `Query` instance that includes all documents in the database that are contained in a collection or subcollection with the given `collectionId`. +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. Signature: ```typescript -export declare function collectionGroup(firestore: Firestore, collectionId: string): Query; +export declare function arrayUnion(...elements: unknown[]): FieldValue; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | A reference to the root Firestore instance. | -| collectionId | string | Identifies the collections to query over. Every collection or subcollection with this ID as the last segment of its path will be included. Cannot contain a slash. | +| elements | unknown\[\] | The elements to union into the array. | Returns: -[Query](./firestore_lite.query.md#query_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> - -The created `Query`. +[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) -## connectFirestoreEmulator() +The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()`. -Modify this instance to communicate with the Cloud Firestore emulator. +## collection() -Note: This must be called before this instance has been used to do any operations. +Gets a `CollectionReference` instance that refers to the collection at the specified absolute path. Signature: ```typescript -export declare function connectFirestoreEmulator(firestore: Firestore, host: string, port: number, options?: { - mockUserToken?: EmulatorMockTokenOptions | string; -}): void; +export declare function collection(firestore: Firestore, path: string, ...pathSegments: string[]): CollectionReference; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | The Firestore instance to configure to connect to the emulator. | -| host | string | the emulator host (ex: localhost). | -| port | number | the emulator port (ex: 9000). | -| options | { mockUserToken?: [EmulatorMockTokenOptions](./util.md#emulatormocktokenoptions) \| string; } | | +| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | A reference to the root Firestore instance. | +| path | string | A slash-separated path to a collection. | +| pathSegments | string\[\] | Additional path segments to apply relative to the first argument. | Returns: -void +[CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> -## doc() +The `CollectionReference` instance. -Gets a `DocumentReference` instance that refers to the document at the specified absolute path. +## Exceptions + +If the final path has an even number of segments and does not point to a collection. + +## collection() + +Gets a `CollectionReference` instance that refers to a subcollection of `reference` at the the specified relative path. Signature: ```typescript -export declare function doc(firestore: Firestore, path: string, ...pathSegments: string[]): DocumentReference; +export declare function collection(reference: CollectionReference, path: string, ...pathSegments: string[]): CollectionReference; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | A reference to the root Firestore instance. | -| path | string | A slash-separated path to a document. | -| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | +| reference | [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<unknown> | A reference to a collection. | +| path | string | A slash-separated path to a collection. | +| pathSegments | string\[\] | Additional path segments to apply relative to the first argument. | Returns: -[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> +[CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> -The `DocumentReference` instance. +The `CollectionReference` instance. ## Exceptions -If the final path has an odd number of segments and does not point to a document. - -## runTransaction() +If the final path has an even number of segments and does not point to a collection. -Executes the given `updateFunction` and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, Cloud Firestore retries the `updateFunction`. If it fails to commit after 5 attempts, the transaction fails. +## collection() -The maximum number of writes allowed in a single transaction is 500. +Gets a `CollectionReference` instance that refers to a subcollection of `reference` at the the specified relative path. Signature: ```typescript -export declare function runTransaction(firestore: Firestore, updateFunction: (transaction: Transaction) => Promise, options?: TransactionOptions): Promise; +export declare function collection(reference: DocumentReference, path: string, ...pathSegments: string[]): CollectionReference; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | A reference to the Firestore database to run this transaction against. | -| updateFunction | (transaction: [Transaction](./firestore_lite.transaction.md#transaction_class)) => Promise<T> | The function to execute within the transaction context. | -| options | [TransactionOptions](./firestore_lite.transactionoptions.md#transactionoptions_interface) | An options object to configure maximum number of attempts to commit. | +| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class) | A reference to a Firestore document. | +| path | string | A slash-separated path to a collection. | +| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | Returns: -Promise<T> - -If the transaction completed successfully or was explicitly aborted (the `updateFunction` returned a failed promise), the promise returned by the `updateFunction `is returned here. Otherwise, if the transaction failed, a rejected promise with the corresponding failure error is returned. +[CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> -## terminate() +The `CollectionReference` instance. -Terminates the provided `Firestore` instance. +## Exceptions -After calling `terminate()` only the `clearIndexedDbPersistence()` functions may be used. Any other function will throw a `FirestoreError`. Termination does not cancel any pending writes, and any promises that are awaiting a response from the server will not be resolved. +If the final path has an even number of segments and does not point to a collection. -To restart after termination, create a new instance of `Firestore` with [getFirestore()](./firestore_.md#getfirestore). +## collectionGroup() -Note: Under normal circumstances, calling `terminate()` is not required. This function is useful only when you want to force this instance to release all of its resources or in combination with [clearIndexedDbPersistence()](./firestore_.md#clearindexeddbpersistence) to ensure that all local state is destroyed between test runs. +Creates and returns a new `Query` instance that includes all documents in the database that are contained in a collection or subcollection with the given `collectionId`. Signature: ```typescript -export declare function terminate(firestore: Firestore): Promise; +export declare function collectionGroup(firestore: Firestore, collectionId: string): Query; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | The Firestore instance to terminate. | +| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | A reference to the root Firestore instance. | +| collectionId | string | Identifies the collections to query over. Every collection or subcollection with this ID as the last segment of its path will be included. Cannot contain a slash. | Returns: -Promise<void> +[Query](./firestore_lite.query.md#query_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> -A `Promise` that is resolved when the instance has been successfully terminated. +The created `Query`. -## writeBatch() +## connectFirestoreEmulator() -Creates a write batch, used for performing multiple writes as a single atomic operation. The maximum number of writes allowed in a single WriteBatch is 500. +Modify this instance to communicate with the Cloud Firestore emulator. -The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. +Note: This must be called before this instance has been used to do any operations. Signature: ```typescript -export declare function writeBatch(firestore: Firestore): WriteBatch; +export declare function connectFirestoreEmulator(firestore: Firestore, host: string, port: number, options?: { + mockUserToken?: EmulatorMockTokenOptions | string; +}): void; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | | +| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | The Firestore instance to configure to connect to the emulator. | +| host | string | the emulator host (ex: localhost). | +| port | number | the emulator port (ex: 9000). | +| options | { mockUserToken?: [EmulatorMockTokenOptions](./util.md#emulatormocktokenoptions) \| string; } | | Returns: -[WriteBatch](./firestore_lite.writebatch.md#writebatch_class) +void -A `WriteBatch` that can be used to atomically execute multiple writes. +## deleteDoc() -## deleteField() +Deletes the document referred to by the specified `DocumentReference`. -Returns a sentinel for use with [updateDoc()](./firestore_lite.md#updatedoc) or [setDoc()](./firestore_lite.md#setdoc) with `{merge: true}` to mark a field for deletion. +The deletion will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the delete fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. Signature: ```typescript -export declare function deleteField(): FieldValue; +export declare function deleteDoc(reference: DocumentReference): Promise; ``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to the document to delete. | + Returns: -[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) +Promise<void> -## documentId() +A `Promise` resolved once the document has been successfully deleted from the backend. -Returns a special sentinel `FieldPath` to refer to the ID of a document. It can be used in queries to sort or filter by the document ID. +## deleteField() + +Returns a sentinel for use with [updateDoc()](./firestore_lite.md#updatedoc) or [setDoc()](./firestore_lite.md#setdoc) with `{merge: true}` to mark a field for deletion. Signature: ```typescript -export declare function documentId(): FieldPath; +export declare function deleteField(): FieldValue; ``` Returns: -[FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) +[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) -## getFirestore() +## doc() -Returns the existing default [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. +Gets a `DocumentReference` instance that refers to the document at the specified absolute path. Signature: ```typescript -export declare function getFirestore(): Firestore; +export declare function doc(firestore: Firestore, path: string, ...pathSegments: string[]): DocumentReference; ``` -Returns: -[Firestore](./firestore_lite.firestore.md#firestore_class) +### Parameters -The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | A reference to the root Firestore instance. | +| path | string | A slash-separated path to a document. | +| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | -## serverTimestamp() +Returns: -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. +[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> -Signature: +The `DocumentReference` instance. -```typescript -export declare function serverTimestamp(): FieldValue; -``` -Returns: +## Exceptions -[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) +If the final path has an odd number of segments and does not point to a document. -## arrayRemove() +## doc() -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. +Gets a `DocumentReference` instance that refers to a document within `reference` at the specified relative path. If no path is specified, an automatically-generated unique ID will be used for the returned `DocumentReference`. Signature: ```typescript -export declare function arrayRemove(...elements: unknown[]): FieldValue; +export declare function doc(reference: CollectionReference, path?: string, ...pathSegments: string[]): DocumentReference; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| elements | unknown\[\] | The elements to remove from the array. | +| reference | [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | A reference to a collection. | +| path | string | A slash-separated path to a document. Has to be omitted to use auto-genrated IDs. | +| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | Returns: -[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) +[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> -The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()` +The `DocumentReference` instance. -## arrayUnion() +## Exceptions -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. +If the final path has an odd number of segments and does not point to a document. + +## doc() + +Gets a `DocumentReference` instance that refers to a document within `reference` at the specified relative path. Signature: ```typescript -export declare function arrayUnion(...elements: unknown[]): FieldValue; +export declare function doc(reference: DocumentReference, path: string, ...pathSegments: string[]): DocumentReference; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| elements | unknown\[\] | The elements to union into the array. | +| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to a Firestore document. | +| path | string | A slash-separated path to a document. | +| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | Returns: -[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) +[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> -The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()`. +The `DocumentReference` instance. -## orderBy() +## Exceptions -Creates a [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class) that sorts the query result by the specified field, optionally in descending order instead of ascending. +If the final path has an odd number of segments and does not point to a document. -Note: Documents that do not contain the specified field will not be present in the query result. +## documentId() + +Returns a special sentinel `FieldPath` to refer to the ID of a document. It can be used in queries to sort or filter by the document ID. Signature: ```typescript -export declare function orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDirection): QueryOrderByConstraint; +export declare function documentId(): FieldPath; +``` +Returns: + +[FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) + +## endAt() + +Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end at the provided document (inclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. + +Signature: + +```typescript +export declare function endAt(snapshot: DocumentSnapshot): QueryConstraint; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| fieldPath | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The field to sort by. | -| directionStr | [OrderByDirection](./firestore_lite.md#orderbydirection) | Optional direction to sort by ('asc' or 'desc'). If not specified, order will be ascending. | +| snapshot | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to end at. | Returns: -[QueryOrderByConstraint](./firestore_lite.queryorderbyconstraint.md#queryorderbyconstraint_class) +[QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) -The created [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class). +A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()` -## where() +## endAt() -Creates a [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) that enforces that documents must contain the specified field and that the value should satisfy the relation constraint provided. +Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. Signature: ```typescript -export declare function where(fieldPath: string | FieldPath, opStr: WhereFilterOp, value: unknown): QueryFieldFilterConstraint; +export declare function endAt(...fieldValues: unknown[]): QueryConstraint; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| fieldPath | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The path to compare | -| opStr | [WhereFilterOp](./firestore_lite.md#wherefilterop) | The operation string (e.g "&lt;", "&lt;=", "==", "&lt;", "&lt;=", "!="). | -| value | unknown | The value for comparison | +| fieldValues | unknown\[\] | The field values to end this query at, in order of the query's order by. | Returns: -[QueryFieldFilterConstraint](./firestore_lite.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) +[QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) -The created [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class). +A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()` -## endAt() +## endBefore() -Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. +Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. Signature: ```typescript -export declare function endAt(...fieldValues: unknown[]): QueryEndAtConstraint; +export declare function endBefore(snapshot: DocumentSnapshot): QueryConstraint; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| fieldValues | unknown\[\] | The field values to end this query at, in order of the query's order by. | +| snapshot | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to end before. | Returns: -[QueryEndAtConstraint](./firestore_lite.queryendatconstraint.md#queryendatconstraint_class) +[QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) -A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` +A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()` ## endBefore() -Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. +Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. Signature: ```typescript -export declare function endBefore(...fieldValues: unknown[]): QueryEndAtConstraint; +export declare function endBefore(...fieldValues: unknown[]): QueryConstraint; ``` ### Parameters @@ -551,156 +566,178 @@ export declare function endBefore(...fieldValues: unknown[]): QueryEndAtConstrai Returns: -[QueryEndAtConstraint](./firestore_lite.queryendatconstraint.md#queryendatconstraint_class) +[QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) -A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` +A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()` -## startAfter() +## getCount() -Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. +Calculates the number of documents in the result set of the given query, without actually downloading the documents. + +Using this function to count the documents is efficient because only the final count, not the documents' data, is downloaded. This function can even count the documents if the result set would be prohibitively large to download entirely (e.g. thousands of documents). Signature: ```typescript -export declare function startAfter(...fieldValues: unknown[]): QueryStartAtConstraint; +export declare function getCount(query: Query): Promise; +}>>; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| fieldValues | unknown\[\] | The field values to start this query after, in order of the query's order by. | +| query | [Query](./firestore_lite.query.md#query_class)<unknown> | The query whose result set size to calculate. | Returns: -[QueryStartAtConstraint](./firestore_lite.querystartatconstraint.md#querystartatconstraint_class) +Promise<[AggregateQuerySnapshot](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<{ count: [AggregateField](./firestore_lite.aggregatefield.md#aggregatefield_class)<number>; }>> -A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()` +A Promise that will be resolved with the count; the count can be retrieved from `snapshot.data().count`, where `snapshot` is the `AggregateQuerySnapshot` to which the returned Promise resolves. -## startAt() +## getDoc() + +Reads the document referred to by the specified document reference. -Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. +All documents are directly fetched from the server, even if the document was previously read or modified. Recent modifications are only reflected in the retrieved `DocumentSnapshot` if they have already been applied by the backend. If the client is offline, the read fails. If you like to use caching or see local modifications, please use the full Firestore SDK. Signature: ```typescript -export declare function startAt(...fieldValues: unknown[]): QueryStartAtConstraint; +export declare function getDoc(reference: DocumentReference): Promise>; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| fieldValues | unknown\[\] | The field values to start this query at, in order of the query's order by. | +| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | The reference of the document to fetch. | Returns: -[QueryStartAtConstraint](./firestore_lite.querystartatconstraint.md#querystartatconstraint_class) +Promise<[DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<T>> -A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()`. +A Promise resolved with a `DocumentSnapshot` containing the current document contents. -## aggregateQuerySnapshotEqual() +## getDocs() -Compares two `AggregateQuerySnapshot` instances for equality. +Executes the query and returns the results as a [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class). -Two `AggregateQuerySnapshot` instances are considered "equal" if they have underlying queries that compare equal, and the same data. +All queries are executed directly by the server, even if the the query was previously executed. Recent modifications are only reflected in the retrieved results if they have already been applied by the backend. If the client is offline, the operation fails. To see previously cached result and local modifications, use the full Firestore SDK. Signature: ```typescript -export declare function aggregateQuerySnapshotEqual(left: AggregateQuerySnapshot, right: AggregateQuerySnapshot): boolean; +export declare function getDocs(query: Query): Promise>; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| left | [AggregateQuerySnapshot](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<T> | The first AggregateQuerySnapshot to compare. | -| right | [AggregateQuerySnapshot](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<T> | The second AggregateQuerySnapshot to compare. | +| query | [Query](./firestore_lite.query.md#query_class)<T> | The Query to execute. | Returns: -boolean +Promise<[QuerySnapshot](./firestore_lite.querysnapshot.md#querysnapshot_class)<T>> -`true` if the objects are "equal", as defined above, or `false` otherwise. +A Promise that will be resolved with the results of the query. -## queryEqual() +## getFirestore() -Returns true if the provided queries point to the same collection and apply the same constraints. +Returns the existing default [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: ```typescript -export declare function queryEqual(left: Query, right: Query): boolean; +export declare function getFirestore(): Firestore; +``` +Returns: + +[Firestore](./firestore_lite.firestore.md#firestore_class) + +The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. + +## 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. + +Signature: + +```typescript +export declare function getFirestore(app: FirebaseApp): Firestore; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| left | [Query](./firestore_lite.query.md#query_class)<T> | A Query to compare. | -| right | [Query](./firestore_lite.query.md#query_class)<T> | A Query to compare. | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance that the returned [Firestore](./firestore_.firestore.md#firestore_class) instance is associated with. | Returns: -boolean +[Firestore](./firestore_lite.firestore.md#firestore_class) -true if the references point to the same location in the same Firestore database. +The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. -## refEqual() +## increment() -Returns true if the provided references are equal. +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 increment the field's current value by the given value. + +If either the operand or the current field value uses floating point precision, all arithmetic follows IEEE 754 semantics. If both values are integers, values outside of JavaScript's safe number range (`Number.MIN_SAFE_INTEGER` to `Number.MAX_SAFE_INTEGER`) are also subject to precision loss. Furthermore, once processed by the Firestore backend, all integer operations are capped between -2^63 and 2^63-1. + +If the current field value is not of type `number`, or if the field does not yet exist, the transformation sets the field to the given value. Signature: ```typescript -export declare function refEqual(left: DocumentReference | CollectionReference, right: DocumentReference | CollectionReference): boolean; +export declare function increment(n: number): FieldValue; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| left | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> \| [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | A reference to compare. | -| right | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> \| [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | A reference to compare. | +| n | number | The value to increment by. | Returns: -boolean +[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) -true if the references point to the same location in the same Firestore database. +The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()` -## snapshotEqual() +## initializeFirestore() -Returns true if the provided snapshots are equal. +Initializes a new instance of Cloud Firestore with the provided settings. Can only be called before any other functions, including [getFirestore()](./firestore_.md#getfirestore). If the custom settings are empty, this function is equivalent to calling [getFirestore()](./firestore_.md#getfirestore). Signature: ```typescript -export declare function snapshotEqual(left: DocumentSnapshot | QuerySnapshot, right: DocumentSnapshot | QuerySnapshot): boolean; +export declare function initializeFirestore(app: FirebaseApp, settings: Settings): Firestore; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| left | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<T> \| [QuerySnapshot](./firestore_lite.querysnapshot.md#querysnapshot_class)<T> | A snapshot to compare. | -| right | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<T> \| [QuerySnapshot](./firestore_lite.querysnapshot.md#querysnapshot_class)<T> | A snapshot to compare. | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) with which the Firestore instance will be associated. | +| settings | [Settings](./firestore_lite.settings.md#settings_interface) | A settings object to configure the Firestore instance. | Returns: -boolean +[Firestore](./firestore_lite.firestore.md#firestore_class) -true if the snapshots are equal. +A newly initialized `Firestore` instance. ## limit() -Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the first matching documents. +Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that only returns the first matching documents. Signature: ```typescript -export declare function limit(limit: number): QueryLimitConstraint; +export declare function limit(limit: number): QueryConstraint; ``` ### Parameters @@ -711,20 +748,20 @@ export declare function limit(limit: number): QueryLimitConstraint; Returns: -[QueryLimitConstraint](./firestore_lite.querylimitconstraint.md#querylimitconstraint_class) +[QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) -The created [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class). +The created [Query](./firestore_.query.md#query_class). ## limitToLast() -Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the last matching documents. +Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that only returns the last matching documents. You must specify at least one `orderBy` clause for `limitToLast` queries, otherwise an exception will be thrown during execution. Signature: ```typescript -export declare function limitToLast(limit: number): QueryLimitConstraint; +export declare function limitToLast(limit: number): QueryConstraint; ``` ### Parameters @@ -735,378 +772,360 @@ export declare function limitToLast(limit: number): QueryLimitConstraint; Returns: -[QueryLimitConstraint](./firestore_lite.querylimitconstraint.md#querylimitconstraint_class) +[QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) -The created [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class). +The created [Query](./firestore_.query.md#query_class). -## setLogLevel() +## orderBy() -Sets the verbosity of Cloud Firestore logs (debug, error, or silent). +Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that sorts the query result by the specified field, optionally in descending order instead of ascending. Signature: ```typescript -export declare function setLogLevel(logLevel: LogLevel): void; +export declare function orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDirection): QueryConstraint; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| logLevel | LogLevel | The verbosity you set for activity and error logging. Can be any of the following values:
  • debug for the most verbose logging level, primarily for debugging.
  • error to log errors only.
  • silent to turn off logging.
| +| fieldPath | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The field to sort by. | +| directionStr | [OrderByDirection](./firestore_lite.md#orderbydirection) | Optional direction to sort by ('asc' or 'desc'). If not specified, order will be ascending. | Returns: -void +[QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) -## increment() +The created [Query](./firestore_.query.md#query_class). -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 increment the field's current value by the given value. +## query() -If either the operand or the current field value uses floating point precision, all arithmetic follows IEEE 754 semantics. If both values are integers, values outside of JavaScript's safe number range (`Number.MIN_SAFE_INTEGER` to `Number.MAX_SAFE_INTEGER`) are also subject to precision loss. Furthermore, once processed by the Firestore backend, all integer operations are capped between -2^63 and 2^63-1. +Creates a new immutable instance of [Query](./firestore_.query.md#query_class) that is extended to also include additional query constraints. -If the current field value is not of type `number`, or if the field does not yet exist, the transformation sets the field to the given value. +Signature: + +```typescript +export declare function query(query: Query, ...queryConstraints: QueryConstraint[]): Query; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./firestore_lite.query.md#query_class)<T> | The [Query](./firestore_.query.md#query_class) instance to use as a base for the new constraints. | +| queryConstraints | [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class)\[\] | The list of [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class)s to apply. | + +Returns: + +[Query](./firestore_lite.query.md#query_class)<T> + +## Exceptions + +if any of the provided query constraints cannot be combined with the existing or new constraints. + +## queryEqual() + +Returns true if the provided queries point to the same collection and apply the same constraints. Signature: ```typescript -export declare function increment(n: number): FieldValue; +export declare function queryEqual(left: Query, right: Query): boolean; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| n | number | The value to increment by. | +| left | [Query](./firestore_lite.query.md#query_class)<T> | A Query to compare. | +| right | [Query](./firestore_lite.query.md#query_class)<T> | A Query to compare. | Returns: -[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) - -The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()` +boolean -## getCount() +true if the references point to the same location in the same Firestore database. -Calculates the number of documents in the result set of the given query, without actually downloading the documents. +## refEqual() -Using this function to count the documents is efficient because only the final count, not the documents' data, is downloaded. This function can even count the documents if the result set would be prohibitively large to download entirely (e.g. thousands of documents). +Returns true if the provided references are equal. Signature: ```typescript -export declare function getCount(query: Query): Promise; -}>>; +export declare function refEqual(left: DocumentReference | CollectionReference, right: DocumentReference | CollectionReference): boolean; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| query | [Query](./firestore_lite.query.md#query_class)<unknown> | The query whose result set size to calculate. | +| left | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> \| [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | A reference to compare. | +| right | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> \| [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | A reference to compare. | Returns: -Promise<[AggregateQuerySnapshot](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<{ count: [AggregateField](./firestore_lite.aggregatefield.md#aggregatefield_class)<number>; }>> +boolean -A Promise that will be resolved with the count; the count can be retrieved from `snapshot.data().count`, where `snapshot` is the `AggregateQuerySnapshot` to which the returned Promise resolves. +true if the references point to the same location in the same Firestore database. -## getDocs() +## runTransaction() -Executes the query and returns the results as a [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class). +Executes the given `updateFunction` and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, Cloud Firestore retries the `updateFunction`. If it fails to commit after 5 attempts, the transaction fails. -All queries are executed directly by the server, even if the the query was previously executed. Recent modifications are only reflected in the retrieved results if they have already been applied by the backend. If the client is offline, the operation fails. To see previously cached result and local modifications, use the full Firestore SDK. +The maximum number of writes allowed in a single transaction is 500. Signature: ```typescript -export declare function getDocs(query: Query): Promise>; +export declare function runTransaction(firestore: Firestore, updateFunction: (transaction: Transaction) => Promise, options?: TransactionOptions): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| query | [Query](./firestore_lite.query.md#query_class)<T> | The Query to execute. | +| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | A reference to the Firestore database to run this transaction against. | +| updateFunction | (transaction: [Transaction](./firestore_lite.transaction.md#transaction_class)) => Promise<T> | The function to execute within the transaction context. | +| options | [TransactionOptions](./firestore_lite.transactionoptions.md#transactionoptions_interface) | An options object to configure maximum number of attempts to commit. | Returns: -Promise<[QuerySnapshot](./firestore_lite.querysnapshot.md#querysnapshot_class)<T>> +Promise<T> -A Promise that will be resolved with the results of the query. +If the transaction completed successfully or was explicitly aborted (the `updateFunction` returned a failed promise), the promise returned by the `updateFunction `is returned here. Otherwise, if the transaction failed, a rejected promise with the corresponding failure error is returned. -## query() +## serverTimestamp() -Creates a new immutable instance of [Query](./firestore_.query.md#query_class) that is extended to also include additional query constraints. +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. Signature: ```typescript -export declare function query(query: Query, ...queryConstraints: QueryConstraint[]): Query; +export declare function serverTimestamp(): FieldValue; ``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./firestore_lite.query.md#query_class)<T> | The [Query](./firestore_.query.md#query_class) instance to use as a base for the new constraints. | -| queryConstraints | [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class)\[\] | The list of [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class)s to apply. | - Returns: -[Query](./firestore_lite.query.md#query_class)<T> - -## Exceptions - -if any of the provided query constraints cannot be combined with the existing or new constraints. +[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) -## addDoc() +## setDoc() -Add a new document to specified `CollectionReference` with the given data, assigning it a document ID automatically. +Writes to the document referred to by the specified `DocumentReference`. If the document does not yet exist, it will be created. The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. Signature: ```typescript -export declare function addDoc(reference: CollectionReference, data: WithFieldValue): Promise>; +export declare function setDoc(reference: DocumentReference, data: WithFieldValue): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| reference | [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | A reference to the collection to add this document to. | -| data | [WithFieldValue](./firestore_lite.md#withfieldvalue)<T> | An Object containing the data for the new document. | +| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to write. | +| data | [WithFieldValue](./firestore_lite.md#withfieldvalue)<T> | A map of the fields and values for the document. | Returns: -Promise<[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T>> +Promise<void> -A `Promise` resolved with a `DocumentReference` pointing to the newly created document after it has been written to the backend. +A `Promise` resolved once the data has been successfully written to the backend. ## Exceptions Error - If the provided input is not a valid Firestore document. -## collection() +## setDoc() -Gets a `CollectionReference` instance that refers to a subcollection of `reference` at the the specified relative path. +Writes to the document referred to by the specified `DocumentReference`. If the document does not yet exist, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. + +The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. Signature: ```typescript -export declare function collection(reference: CollectionReference, path: string, ...pathSegments: string[]): CollectionReference; +export declare function setDoc(reference: DocumentReference, data: PartialWithFieldValue, options: SetOptions): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| reference | [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<unknown> | A reference to a collection. | -| path | string | A slash-separated path to a collection. | -| pathSegments | string\[\] | Additional path segments to apply relative to the first argument. | +| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to write. | +| data | [PartialWithFieldValue](./firestore_lite.md#partialwithfieldvalue)<T> | A map of the fields and values for the document. | +| options | [SetOptions](./firestore_lite.md#setoptions) | An object to configure the set behavior. | Returns: -[CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> +Promise<void> -The `CollectionReference` instance. +A `Promise` resolved once the data has been successfully written to the backend. ## Exceptions -If the final path has an even number of segments and does not point to a collection. +Error - If the provided input is not a valid Firestore document. -## collection() +## setLogLevel() -Gets a `CollectionReference` instance that refers to a subcollection of `reference` at the the specified relative path. +Sets the verbosity of Cloud Firestore logs (debug, error, or silent). Signature: ```typescript -export declare function collection(reference: DocumentReference, path: string, ...pathSegments: string[]): CollectionReference; +export declare function setLogLevel(logLevel: LogLevel): void; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class) | A reference to a Firestore document. | -| path | string | A slash-separated path to a collection. | -| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | +| logLevel | LogLevel | The verbosity you set for activity and error logging. Can be any of the following values:
  • debug for the most verbose logging level, primarily for debugging.
  • error to log errors only.
  • silent to turn off logging.
| Returns: -[CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> - -The `CollectionReference` instance. - -## Exceptions - -If the final path has an even number of segments and does not point to a collection. - -## deleteDoc() +void -Deletes the document referred to by the specified `DocumentReference`. +## snapshotEqual() -The deletion will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the delete fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. +Returns true if the provided snapshots are equal. Signature: ```typescript -export declare function deleteDoc(reference: DocumentReference): Promise; +export declare function snapshotEqual(left: DocumentSnapshot | QuerySnapshot, right: DocumentSnapshot | QuerySnapshot): boolean; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to the document to delete. | +| left | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<T> \| [QuerySnapshot](./firestore_lite.querysnapshot.md#querysnapshot_class)<T> | A snapshot to compare. | +| right | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<T> \| [QuerySnapshot](./firestore_lite.querysnapshot.md#querysnapshot_class)<T> | A snapshot to compare. | Returns: -Promise<void> +boolean -A `Promise` resolved once the document has been successfully deleted from the backend. +true if the snapshots are equal. -## doc() +## startAfter() -Gets a `DocumentReference` instance that refers to a document within `reference` at the specified relative path. If no path is specified, an automatically-generated unique ID will be used for the returned `DocumentReference`. +Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. Signature: ```typescript -export declare function doc(reference: CollectionReference, path?: string, ...pathSegments: string[]): DocumentReference; +export declare function startAfter(snapshot: DocumentSnapshot): QueryConstraint; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| reference | [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | A reference to a collection. | -| path | string | A slash-separated path to a document. Has to be omitted to use auto-genrated IDs. | -| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | +| snapshot | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to start after. | Returns: -[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> - -The `DocumentReference` instance. - -## Exceptions +[QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) -If the final path has an odd number of segments and does not point to a document. +A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()` -## doc() +## startAfter() -Gets a `DocumentReference` instance that refers to a document within `reference` at the specified relative path. +Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. Signature: ```typescript -export declare function doc(reference: DocumentReference, path: string, ...pathSegments: string[]): DocumentReference; +export declare function startAfter(...fieldValues: unknown[]): QueryConstraint; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to a Firestore document. | -| path | string | A slash-separated path to a document. | -| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | +| fieldValues | unknown\[\] | The field values to start this query after, in order of the query's order by. | Returns: -[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> - -The `DocumentReference` instance. - -## Exceptions - -If the final path has an odd number of segments and does not point to a document. +[QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) -## getDoc() +A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()` -Reads the document referred to by the specified document reference. +## startAt() -All documents are directly fetched from the server, even if the document was previously read or modified. Recent modifications are only reflected in the retrieved `DocumentSnapshot` if they have already been applied by the backend. If the client is offline, the read fails. If you like to use caching or see local modifications, please use the full Firestore SDK. +Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the `orderBy` of this query. Signature: ```typescript -export declare function getDoc(reference: DocumentReference): Promise>; +export declare function startAt(snapshot: DocumentSnapshot): QueryConstraint; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | The reference of the document to fetch. | +| snapshot | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to start at. | Returns: -Promise<[DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<T>> - -A Promise resolved with a `DocumentSnapshot` containing the current document contents. +[QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) -## setDoc() +A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()`. -Writes to the document referred to by the specified `DocumentReference`. If the document does not yet exist, it will be created. +## startAt() -The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. +Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. Signature: ```typescript -export declare function setDoc(reference: DocumentReference, data: WithFieldValue): Promise; +export declare function startAt(...fieldValues: unknown[]): QueryConstraint; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to write. | -| data | [WithFieldValue](./firestore_lite.md#withfieldvalue)<T> | A map of the fields and values for the document. | +| fieldValues | unknown\[\] | The field values to start this query at, in order of the query's order by. | Returns: -Promise<void> +[QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) -A `Promise` resolved once the data has been successfully written to the backend. +A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()`. -## Exceptions +## terminate() -Error - If the provided input is not a valid Firestore document. +Terminates the provided `Firestore` instance. -## setDoc() +After calling `terminate()` only the `clearIndexedDbPersistence()` functions may be used. Any other function will throw a `FirestoreError`. Termination does not cancel any pending writes, and any promises that are awaiting a response from the server will not be resolved. -Writes to the document referred to by the specified `DocumentReference`. If the document does not yet exist, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. +To restart after termination, create a new instance of `Firestore` with [getFirestore()](./firestore_.md#getfirestore). -The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. +Note: Under normal circumstances, calling `terminate()` is not required. This function is useful only when you want to force this instance to release all of its resources or in combination with [clearIndexedDbPersistence()](./firestore_.md#clearindexeddbpersistence) to ensure that all local state is destroyed between test runs. Signature: ```typescript -export declare function setDoc(reference: DocumentReference, data: PartialWithFieldValue, options: SetOptions): Promise; +export declare function terminate(firestore: Firestore): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to write. | -| data | [PartialWithFieldValue](./firestore_lite.md#partialwithfieldvalue)<T> | A map of the fields and values for the document. | -| options | [SetOptions](./firestore_lite.md#setoptions) | An object to configure the set behavior. | +| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | The Firestore instance to terminate. | Returns: Promise<void> -A `Promise` resolved once the data has been successfully written to the backend. - -## Exceptions - -Error - If the provided input is not a valid Firestore document. +A `Promise` that is resolved when the instance has been successfully terminated. ## updateDoc() @@ -1170,93 +1189,53 @@ A `Promise` resolved once the data has been successfully written to the backend. Error - If the provided input is not valid Firestore data. -## endAt() - -Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided document (inclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. - -Signature: - -```typescript -export declare function endAt(snapshot: DocumentSnapshot): QueryEndAtConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| snapshot | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to end at. | - -Returns: - -[QueryEndAtConstraint](./firestore_lite.queryendatconstraint.md#queryendatconstraint_class) - -A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` - -## endBefore() +## where() -Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. +Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that enforces that documents must contain the specified field and that the value should satisfy the relation constraint provided. Signature: ```typescript -export declare function endBefore(snapshot: DocumentSnapshot): QueryEndAtConstraint; +export declare function where(fieldPath: string | FieldPath, opStr: WhereFilterOp, value: unknown): QueryConstraint; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| snapshot | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to end before. | +| fieldPath | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The path to compare | +| opStr | [WhereFilterOp](./firestore_lite.md#wherefilterop) | The operation string (e.g "&lt;", "&lt;=", "==", "&lt;", "&lt;=", "!="). | +| value | unknown | The value for comparison | Returns: -[QueryEndAtConstraint](./firestore_lite.queryendatconstraint.md#queryendatconstraint_class) - -A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` +[QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) -## startAfter() - -Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. - -Signature: - -```typescript -export declare function startAfter(snapshot: DocumentSnapshot): QueryStartAtConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| snapshot | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to start after. | - -Returns: - -[QueryStartAtConstraint](./firestore_lite.querystartatconstraint.md#querystartatconstraint_class) +The created [Query](./firestore_.query.md#query_class). -A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()` +## writeBatch() -## startAt() +Creates a write batch, used for performing multiple writes as a single atomic operation. The maximum number of writes allowed in a single WriteBatch is 500. -Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the `orderBy` of this query. +The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. Signature: ```typescript -export declare function startAt(snapshot: DocumentSnapshot): QueryStartAtConstraint; +export declare function writeBatch(firestore: Firestore): WriteBatch; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| snapshot | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to start at. | +| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | | Returns: -[QueryStartAtConstraint](./firestore_lite.querystartatconstraint.md#querystartatconstraint_class) +[WriteBatch](./firestore_lite.writebatch.md#writebatch_class) -A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()`. +A `WriteBatch` that can be used to atomically execute multiple writes. ## AddPrefixToKeys @@ -1372,16 +1351,6 @@ Describes the different query constraints available in this SDK. export declare type QueryConstraintType = 'where' | 'orderBy' | 'limit' | 'limitToLast' | 'startAt' | 'startAfter' | 'endAt' | 'endBefore'; ``` -## QueryNonFilterConstraint - -`QueryNonFilterConstraint` is a helper union type that represents QueryConstraints which are used to narrow or order the set of documents, but that do not explicitly filter on a document field. `QueryNonFilterConstraint`s are created by invoking [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains the `QueryConstraint`. - -Signature: - -```typescript -export declare type QueryNonFilterConstraint = QueryOrderByConstraint | QueryLimitConstraint | QueryStartAtConstraint | QueryEndAtConstraint; -``` - ## SetOptions An options object that configures the behavior of [setDoc()](./firestore_lite.md#setdoc), and calls. These calls can be configured to perform granular merges instead of overwriting the target documents in their entirety by providing a `SetOptions` with `merge: true`. diff --git a/docs-devsite/firestore_lite.queryconstraint.md b/docs-devsite/firestore_lite.queryconstraint.md index dae8d5f0069..13bda202cb5 100644 --- a/docs-devsite/firestore_lite.queryconstraint.md +++ b/docs-devsite/firestore_lite.queryconstraint.md @@ -10,7 +10,7 @@ https://github.com/firebase/firebase-js-sdk {% endcomment %} # QueryConstraint class -A `QueryConstraint` is used to narrow the set of documents returned by a Firestore query. `QueryConstraint`s are created by invoking [where()](./firestore_.md#where), [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit), [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryConstraint`. +A `QueryConstraint` is used to narrow the set of documents returned by a Firestore query. `QueryConstraint`s are created by invoking [where()](./firestore_.md#where), [orderBy()](./firestore_.md#orderby), [startAt()](./firestore_.md#startat), [startAfter()](./firestore_.md#startafter), , [endAt()](./firestore_.md#endat), [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryConstraint`. Signature: @@ -22,11 +22,11 @@ export declare abstract class QueryConstraint | Property | Modifiers | Type | Description | | --- | --- | --- | --- | -| [type](./firestore_lite.queryconstraint.md#queryconstrainttype) | | [QueryConstraintType](./firestore_lite.md#queryconstrainttype) | The type of this query constraint | +| [type](./firestore_lite.queryconstraint.md#queryconstrainttype) | | [QueryConstraintType](./firestore_lite.md#queryconstrainttype) | The type of this query constraints | ## QueryConstraint.type -The type of this query constraint +The type of this query constraints Signature: diff --git a/docs-devsite/functions.md b/docs-devsite/functions.md index 35b5087e08e..dd17ed38752 100644 --- a/docs-devsite/functions.md +++ b/docs-devsite/functions.md @@ -16,10 +16,8 @@ Cloud Functions for Firebase | Function | Description | | --- | --- | -| function(app...) | -| [getFunctions(app, regionOrCustomDomain)](./functions.md#getfunctions) | Returns a [Functions](./functions.functions.md#functions_interface) instance for the given app. | -| function(functionsInstance...) | | [connectFunctionsEmulator(functionsInstance, host, port)](./functions.md#connectfunctionsemulator) | Modify this instance to communicate with the Cloud Functions emulator.Note: this must be called before this instance has been used to do any operations. | +| [getFunctions(app, regionOrCustomDomain)](./functions.md#getfunctions) | Returns a [Functions](./functions.functions.md#functions_interface) instance for the given app. | | [httpsCallable(functionsInstance, name, options)](./functions.md#httpscallable) | Returns a reference to the callable HTTPS trigger with the given name. | | [httpsCallableFromURL(functionsInstance, url, options)](./functions.md#httpscallablefromurl) | Returns a reference to the callable HTTPS trigger with the specified url. | @@ -40,50 +38,50 @@ Cloud Functions for Firebase | [FunctionsErrorCodeCore](./functions.md#functionserrorcodecore) | Functions error code string appended after "functions/" product prefix. See [FunctionsErrorCode](./functions.md#functionserrorcode) for full documentation of codes. | | [HttpsCallable](./functions.md#httpscallable) | A reference to a "callable" HTTP trigger in Google Cloud Functions. | -## getFunctions() +## connectFunctionsEmulator() -Returns a [Functions](./functions.functions.md#functions_interface) instance for the given app. +Modify this instance to communicate with the Cloud Functions emulator. + +Note: this must be called before this instance has been used to do any operations. Signature: ```typescript -export declare function getFunctions(app?: FirebaseApp, regionOrCustomDomain?: string): Functions; +export declare function connectFunctionsEmulator(functionsInstance: Functions, host: string, port: number): void; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to use. | -| regionOrCustomDomain | string | one of: a) The region the callable functions are located in (ex: us-central1) b) A custom domain hosting the callable functions (ex: https://mydomain.com) | +| functionsInstance | [Functions](./functions.functions.md#functions_interface) | | +| host | string | The emulator host (ex: localhost) | +| port | number | The emulator port (ex: 5001) | Returns: -[Functions](./functions.functions.md#functions_interface) - -## connectFunctionsEmulator() +void -Modify this instance to communicate with the Cloud Functions emulator. +## getFunctions() -Note: this must be called before this instance has been used to do any operations. +Returns a [Functions](./functions.functions.md#functions_interface) instance for the given app. Signature: ```typescript -export declare function connectFunctionsEmulator(functionsInstance: Functions, host: string, port: number): void; +export declare function getFunctions(app?: FirebaseApp, regionOrCustomDomain?: string): Functions; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| functionsInstance | [Functions](./functions.functions.md#functions_interface) | | -| host | string | The emulator host (ex: localhost) | -| port | number | The emulator port (ex: 5001) | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to use. | +| regionOrCustomDomain | string | one of: a) The region the callable functions are located in (ex: us-central1) b) A custom domain hosting the callable functions (ex: https://mydomain.com) | Returns: -void +[Functions](./functions.functions.md#functions_interface) ## httpsCallable() diff --git a/docs-devsite/installations.md b/docs-devsite/installations.md index 1ef8b80b00e..0e234c6b7ed 100644 --- a/docs-devsite/installations.md +++ b/docs-devsite/installations.md @@ -16,11 +16,9 @@ Firebase Installations | Function | Description | | --- | --- | -| function(app...) | -| [getInstallations(app)](./installations.md#getinstallations) | Returns an instance of [Installations](./installations.installations.md#installations_interface) associated with the given [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. | -| function(installations...) | | [deleteInstallations(installations)](./installations.md#deleteinstallations) | Deletes the Firebase Installation and all associated data. | | [getId(installations)](./installations.md#getid) | Creates a Firebase Installation if there isn't one for the app and returns the Installation ID. | +| [getInstallations(app)](./installations.md#getinstallations) | Returns an instance of [Installations](./installations.installations.md#installations_interface) associated with the given [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. | | [getToken(installations, forceRefresh)](./installations.md#gettoken) | Returns a Firebase Installations auth token, identifying the current Firebase Installation. | | [onIdChange(installations, callback)](./installations.md#onidchange) | Sets a new callback that will get called when Installation ID changes. Returns an unsubscribe function that will remove the callback when called. | @@ -37,34 +35,34 @@ Firebase Installations | [IdChangeCallbackFn](./installations.md#idchangecallbackfn) | An user defined callback function that gets called when Installations ID changes. | | [IdChangeUnsubscribeFn](./installations.md#idchangeunsubscribefn) | Unsubscribe a callback function previously added via [IdChangeCallbackFn](./installations.md#idchangecallbackfn). | -## getInstallations() +## deleteInstallations() -Returns an instance of [Installations](./installations.installations.md#installations_interface) associated with the given [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. +Deletes the Firebase Installation and all associated data. Signature: ```typescript -export declare function getInstallations(app?: FirebaseApp): Installations; +export declare function deleteInstallations(installations: Installations): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. | +| installations | [Installations](./installations.installations.md#installations_interface) | The Installations instance. | Returns: -[Installations](./installations.installations.md#installations_interface) +Promise<void> -## deleteInstallations() +## getId() -Deletes the Firebase Installation and all associated data. +Creates a Firebase Installation if there isn't one for the app and returns the Installation ID. Signature: ```typescript -export declare function deleteInstallations(installations: Installations): Promise; +export declare function getId(installations: Installations): Promise; ``` ### Parameters @@ -75,27 +73,27 @@ export declare function deleteInstallations(installations: Installations): Promi Returns: -Promise<void> +Promise<string> -## getId() +## getInstallations() -Creates a Firebase Installation if there isn't one for the app and returns the Installation ID. +Returns an instance of [Installations](./installations.installations.md#installations_interface) associated with the given [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. Signature: ```typescript -export declare function getId(installations: Installations): Promise; +export declare function getInstallations(app?: FirebaseApp): Installations; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| installations | [Installations](./installations.installations.md#installations_interface) | The Installations instance. | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. | Returns: -Promise<string> +[Installations](./installations.installations.md#installations_interface) ## getToken() diff --git a/docs-devsite/messaging_.md b/docs-devsite/messaging_.md index ad04429ac94..71cd4a63608 100644 --- a/docs-devsite/messaging_.md +++ b/docs-devsite/messaging_.md @@ -15,14 +15,11 @@ https://github.com/firebase/firebase-js-sdk | Function | Description | | --- | --- | -| function(app...) | -| [getMessaging(app)](./messaging_.md#getmessaging) | Retrieves a Firebase Cloud Messaging instance. | -| function(messaging...) | | [deleteToken(messaging)](./messaging_.md#deletetoken) | Deletes the registration token associated with this [Messaging](./messaging_.messaging.md#messaging_interface) instance and unsubscribes the [Messaging](./messaging_.messaging.md#messaging_interface) instance from the push subscription. | +| [getMessaging(app)](./messaging_.md#getmessaging) | Retrieves a Firebase Cloud Messaging instance. | | [getToken(messaging, options)](./messaging_.md#gettoken) | Subscribes the [Messaging](./messaging_.messaging.md#messaging_interface) instance to push notifications. Returns an Firebase Cloud Messaging registration token that can be used to send push messages to that [Messaging](./messaging_.messaging.md#messaging_interface) instance.If a notification permission isn't already granted, this method asks the user for permission. The returned promise rejects if the user does not allow the app to show notifications. | -| [onMessage(messaging, nextOrObserver)](./messaging_.md#onmessage) | When a push message is received and the user is currently on a page for your origin, the message is passed to the page and an onMessage() event is dispatched with the payload of the push message. | -| function() | | [isSupported()](./messaging_.md#issupported) | Checks if all required APIs exist in the browser. | +| [onMessage(messaging, nextOrObserver)](./messaging_.md#onmessage) | When a push message is received and the user is currently on a page for your origin, the message is passed to the page and an onMessage() event is dispatched with the payload of the push message. | ## Interfaces @@ -34,49 +31,49 @@ https://github.com/firebase/firebase-js-sdk | [Messaging](./messaging_.messaging.md#messaging_interface) | Public interface of the Firebase Cloud Messaging SDK. | | [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) | Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) | -## getMessaging() +## deleteToken() -Retrieves a Firebase Cloud Messaging instance. +Deletes the registration token associated with this [Messaging](./messaging_.messaging.md#messaging_interface) instance and unsubscribes the [Messaging](./messaging_.messaging.md#messaging_interface) instance from the push subscription. Signature: ```typescript -export declare function getMessagingInWindow(app?: FirebaseApp): Messaging; +export declare function deleteToken(messaging: Messaging): Promise; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | | +| messaging | [Messaging](./messaging_.messaging.md#messaging_interface) | The [Messaging](./messaging_.messaging.md#messaging_interface) instance. | Returns: -[Messaging](./messaging_.messaging.md#messaging_interface) +Promise<boolean> -The Firebase Cloud Messaging instance associated with the provided firebase app. +The promise resolves when the token has been successfully deleted. -## deleteToken() +## getMessaging() -Deletes the registration token associated with this [Messaging](./messaging_.messaging.md#messaging_interface) instance and unsubscribes the [Messaging](./messaging_.messaging.md#messaging_interface) instance from the push subscription. +Retrieves a Firebase Cloud Messaging instance. Signature: ```typescript -export declare function deleteToken(messaging: Messaging): Promise; +export declare function getMessagingInWindow(app?: FirebaseApp): Messaging; ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | -| messaging | [Messaging](./messaging_.messaging.md#messaging_interface) | The [Messaging](./messaging_.messaging.md#messaging_interface) instance. | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | | Returns: -Promise<boolean> +[Messaging](./messaging_.messaging.md#messaging_interface) -The promise resolves when the token has been successfully deleted. +The Firebase Cloud Messaging instance associated with the provided firebase app. ## getToken() @@ -103,6 +100,21 @@ Promise<string> The promise resolves with an FCM registration token. +## isSupported() + +Checks if all required APIs exist in the browser. + +Signature: + +```typescript +export declare function isWindowSupported(): Promise; +``` +Returns: + +Promise<boolean> + +a Promise that resolves to a boolean. + ## onMessage() When a push message is received and the user is currently on a page for your origin, the message is passed to the page and an `onMessage()` event is dispatched with the payload of the push message. @@ -126,18 +138,3 @@ export declare function onMessage(messaging: Messaging, nextOrObserver: NextFnSignature: - -```typescript -export declare function isWindowSupported(): Promise; -``` -Returns: - -Promise<boolean> - -a Promise that resolves to a boolean. - diff --git a/docs-devsite/messaging_.notificationpayload.md b/docs-devsite/messaging_.notificationpayload.md index 5978a55b6bf..c063d346787 100644 --- a/docs-devsite/messaging_.notificationpayload.md +++ b/docs-devsite/messaging_.notificationpayload.md @@ -23,7 +23,6 @@ export interface NotificationPayload | Property | Type | Description | | --- | --- | --- | | [body](./messaging_.notificationpayload.md#notificationpayloadbody) | string | The notification's body text. | -| [icon](./messaging_.notificationpayload.md#notificationpayloadicon) | string | The URL to use for the notification's icon. If you don't send this key in the request, FCM displays the launcher icon specified in your app manifest. | | [image](./messaging_.notificationpayload.md#notificationpayloadimage) | string | The URL of an image that is downloaded on the device and displayed in the notification. | | [title](./messaging_.notificationpayload.md#notificationpayloadtitle) | string | The notification's title. | @@ -37,16 +36,6 @@ The notification's body text. body?: string; ``` -## NotificationPayload.icon - -The URL to use for the notification's icon. If you don't send this key in the request, FCM displays the launcher icon specified in your app manifest. - -Signature: - -```typescript -icon?: string; -``` - ## NotificationPayload.image The URL of an image that is downloaded on the device and displayed in the notification. diff --git a/docs-devsite/messaging_sw.md b/docs-devsite/messaging_sw.md index 0950fc61034..4b183b00e9a 100644 --- a/docs-devsite/messaging_sw.md +++ b/docs-devsite/messaging_sw.md @@ -15,13 +15,10 @@ https://github.com/firebase/firebase-js-sdk | Function | Description | | --- | --- | -| function(app...) | -| [getMessaging(app)](./messaging_sw.md#getmessaging) | Retrieves a Firebase Cloud Messaging instance. | -| function(messaging...) | | [experimentalSetDeliveryMetricsExportedToBigQueryEnabled(messaging, enable)](./messaging_sw.md#experimentalsetdeliverymetricsexportedtobigqueryenabled) | Enables or disables Firebase Cloud Messaging message delivery metrics export to BigQuery. By default, message delivery metrics are not exported to BigQuery. Use this method to enable or disable the export at runtime. | -| [onBackgroundMessage(messaging, nextOrObserver)](./messaging_sw.md#onbackgroundmessage) | Called when a message is received while the app is in the background. An app is considered to be in the background if no active window is displayed. | -| function() | +| [getMessaging(app)](./messaging_sw.md#getmessaging) | Retrieves a Firebase Cloud Messaging instance. | | [isSupported()](./messaging_sw.md#issupported) | Checks whether all required APIs exist within SW Context | +| [onBackgroundMessage(messaging, nextOrObserver)](./messaging_sw.md#onbackgroundmessage) | Called when a message is received while the app is in the background. An app is considered to be in the background if no active window is displayed. | ## Interfaces @@ -33,6 +30,27 @@ https://github.com/firebase/firebase-js-sdk | [Messaging](./messaging_sw.messaging.md#messaging_interface) | Public interface of the Firebase Cloud Messaging SDK. | | [NotificationPayload](./messaging_sw.notificationpayload.md#notificationpayload_interface) | Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) | +## experimentalSetDeliveryMetricsExportedToBigQueryEnabled() + +Enables or disables Firebase Cloud Messaging message delivery metrics export to BigQuery. By default, message delivery metrics are not exported to BigQuery. Use this method to enable or disable the export at runtime. + +Signature: + +```typescript +export declare function experimentalSetDeliveryMetricsExportedToBigQueryEnabled(messaging: Messaging, enable: boolean): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| messaging | [Messaging](./messaging_.messaging.md#messaging_interface) | The FirebaseMessaging instance. | +| enable | boolean | Whether Firebase Cloud Messaging should export message delivery metrics to BigQuery. | + +Returns: + +void + ## getMessaging() Retrieves a Firebase Cloud Messaging instance. @@ -55,26 +73,20 @@ export declare function getMessagingInSw(app?: FirebaseApp): Messaging; The Firebase Cloud Messaging instance associated with the provided firebase app. -## experimentalSetDeliveryMetricsExportedToBigQueryEnabled() +## isSupported() -Enables or disables Firebase Cloud Messaging message delivery metrics export to BigQuery. By default, message delivery metrics are not exported to BigQuery. Use this method to enable or disable the export at runtime. +Checks whether all required APIs exist within SW Context Signature: ```typescript -export declare function experimentalSetDeliveryMetricsExportedToBigQueryEnabled(messaging: Messaging, enable: boolean): void; +export declare function isSwSupported(): Promise; ``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| messaging | [Messaging](./messaging_.messaging.md#messaging_interface) | The FirebaseMessaging instance. | -| enable | boolean | Whether Firebase Cloud Messaging should export message delivery metrics to BigQuery. | - Returns: -void +Promise<boolean> + +a Promise that resolves to a boolean. ## onBackgroundMessage() @@ -99,18 +111,3 @@ export declare function onBackgroundMessage(messaging: Messaging, nextOrObserver To stop listening for messages execute this returned function -## isSupported() - -Checks whether all required APIs exist within SW Context - -Signature: - -```typescript -export declare function isSwSupported(): Promise; -``` -Returns: - -Promise<boolean> - -a Promise that resolves to a boolean. - diff --git a/docs-devsite/messaging_sw.notificationpayload.md b/docs-devsite/messaging_sw.notificationpayload.md index c49ecfdf123..e4ac4e73f66 100644 --- a/docs-devsite/messaging_sw.notificationpayload.md +++ b/docs-devsite/messaging_sw.notificationpayload.md @@ -23,7 +23,6 @@ export interface NotificationPayload | Property | Type | Description | | --- | --- | --- | | [body](./messaging_sw.notificationpayload.md#notificationpayloadbody) | string | The notification's body text. | -| [icon](./messaging_sw.notificationpayload.md#notificationpayloadicon) | string | The URL to use for the notification's icon. If you don't send this key in the request, FCM displays the launcher icon specified in your app manifest. | | [image](./messaging_sw.notificationpayload.md#notificationpayloadimage) | string | The URL of an image that is downloaded on the device and displayed in the notification. | | [title](./messaging_sw.notificationpayload.md#notificationpayloadtitle) | string | The notification's title. | @@ -37,16 +36,6 @@ The notification's body text. body?: string; ``` -## NotificationPayload.icon - -The URL to use for the notification's icon. If you don't send this key in the request, FCM displays the launcher icon specified in your app manifest. - -Signature: - -```typescript -icon?: string; -``` - ## NotificationPayload.image The URL of an image that is downloaded on the device and displayed in the notification. diff --git a/docs-devsite/performance.md b/docs-devsite/performance.md index 247002ed70a..bcc2ce5c836 100644 --- a/docs-devsite/performance.md +++ b/docs-devsite/performance.md @@ -16,10 +16,8 @@ Firebase Performance Monitoring | Function | Description | | --- | --- | -| function(app...) | | [getPerformance(app)](./performance.md#getperformance) | Returns a [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) instance for the given app. | | [initializePerformance(app, settings)](./performance.md#initializeperformance) | Returns a [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) instance for the given app. Can only be called once. | -| function(performance...) | | [trace(performance, name)](./performance.md#trace) | Returns a new PerformanceTrace instance. | ## Interfaces diff --git a/docs-devsite/remote-config.md b/docs-devsite/remote-config.md index 5011c3b12b9..e192d093d7b 100644 --- a/docs-devsite/remote-config.md +++ b/docs-devsite/remote-config.md @@ -16,9 +16,6 @@ Firebase Remote Config | Function | Description | | --- | --- | -| function(app...) | -| [getRemoteConfig(app)](./remote-config.md#getremoteconfig) | | -| function(remoteConfig...) | | [activate(remoteConfig)](./remote-config.md#activate) | Makes the last fetched config available to the getters. | | [ensureInitialized(remoteConfig)](./remote-config.md#ensureinitialized) | Ensures the last activated config are available to the getters. | | [fetchAndActivate(remoteConfig)](./remote-config.md#fetchandactivate) | Performs fetch and activate operations, as a convenience. | @@ -26,11 +23,11 @@ Firebase Remote Config | [getAll(remoteConfig)](./remote-config.md#getall) | Gets all config. | | [getBoolean(remoteConfig, key)](./remote-config.md#getboolean) | Gets the value for the given key as a boolean.Convenience method for calling remoteConfig.getValue(key).asBoolean(). | | [getNumber(remoteConfig, key)](./remote-config.md#getnumber) | Gets the value for the given key as a number.Convenience method for calling remoteConfig.getValue(key).asNumber(). | +| [getRemoteConfig(app)](./remote-config.md#getremoteconfig) | | | [getString(remoteConfig, key)](./remote-config.md#getstring) | Gets the value for the given key as a string. Convenience method for calling remoteConfig.getValue(key).asString(). | | [getValue(remoteConfig, key)](./remote-config.md#getvalue) | Gets the [Value](./remote-config.value.md#value_interface) for the given key. | -| [setLogLevel(remoteConfig, logLevel)](./remote-config.md#setloglevel) | Defines the log level to use. | -| function() | | [isSupported()](./remote-config.md#issupported) | This method provides two different checks:1. Check if IndexedDB exists in the browser environment. 2. Check if the current browser context allows IndexedDB open() calls. | +| [setLogLevel(remoteConfig, logLevel)](./remote-config.md#setloglevel) | Defines the log level to use. | ## Interfaces @@ -48,26 +45,6 @@ Firebase Remote Config | [LogLevel](./remote-config.md#loglevel) | Defines levels of Remote Config logging. | | [ValueSource](./remote-config.md#valuesource) | Indicates the source of a value.
  • "static" indicates the value was defined by a static constant.
  • "default" indicates the value was defined by default config.
  • "remote" indicates the value was defined by fetched config.
| -## getRemoteConfig() - -Signature: - -```typescript -export declare function getRemoteConfig(app?: FirebaseApp): RemoteConfig; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. | - -Returns: - -[RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) - -A [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. - ## activate() Makes the last fetched config available to the getters. @@ -226,6 +203,26 @@ number The value for the given key as a number. +## getRemoteConfig() + +Signature: + +```typescript +export declare function getRemoteConfig(app?: FirebaseApp): RemoteConfig; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. | + +Returns: + +[RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) + +A [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. + ## getString() Gets the value for the given key as a string. Convenience method for calling remoteConfig.getValue(key).asString(). @@ -272,6 +269,23 @@ export declare function getValue(remoteConfig: RemoteConfig, key: string): Value The value for the given key. +## isSupported() + +This method provides two different checks: + +1. Check if IndexedDB exists in the browser environment. 2. Check if the current browser context allows IndexedDB `open()` calls. + +Signature: + +```typescript +export declare function isSupported(): Promise; +``` +Returns: + +Promise<boolean> + +A `Promise` which resolves to true if a [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance can be initialized in this environment, or false if it cannot. + ## setLogLevel() Defines the log level to use. @@ -293,23 +307,6 @@ export declare function setLogLevel(remoteConfig: RemoteConfig, logLevel: Remote void -## isSupported() - -This method provides two different checks: - -1. Check if IndexedDB exists in the browser environment. 2. Check if the current browser context allows IndexedDB `open()` calls. - -Signature: - -```typescript -export declare function isSupported(): Promise; -``` -Returns: - -Promise<boolean> - -A `Promise` which resolves to true if a [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance can be initialized in this environment, or false if it cannot. - ## FetchStatus Summarizes the outcome of the last attempt to fetch config from the Firebase Remote Config server. diff --git a/docs-devsite/storage.md b/docs-devsite/storage.md index 0aab0c6a35d..dc92633ec0d 100644 --- a/docs-devsite/storage.md +++ b/docs-devsite/storage.md @@ -16,38 +16,22 @@ Cloud Storage for Firebase | Function | Description | | --- | --- | -| function(app...) | -| [getStorage(app, bucketUrl)](./storage.md#getstorage) | Gets a [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance for the given Firebase app. | -| function(storage...) | | [connectStorageEmulator(storage, host, port, options)](./storage.md#connectstorageemulator) | Modify this [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance to communicate with the Cloud Storage emulator. | -| [ref(storage, url)](./storage.md#ref) | Returns a [StorageReference](./storage.storagereference.md#storagereference_interface) for the given url. | -| function(ref...) | | [deleteObject(ref)](./storage.md#deleteobject) | Deletes the object at this location. | | [getBlob(ref, maxDownloadSizeBytes)](./storage.md#getblob) | Downloads the data at the object's location. Returns an error if the object is not found.To use this functionality, you have to whitelist your app's origin in your Cloud Storage bucket. See also https://cloud.google.com/storage/docs/configuring-corsThis API is not available in Node. | | [getBytes(ref, maxDownloadSizeBytes)](./storage.md#getbytes) | Downloads the data at the object's location. Returns an error if the object is not found.To use this functionality, you have to whitelist your app's origin in your Cloud Storage bucket. See also https://cloud.google.com/storage/docs/configuring-cors | | [getDownloadURL(ref)](./storage.md#getdownloadurl) | Returns the download URL for the given [StorageReference](./storage.storagereference.md#storagereference_interface). | | [getMetadata(ref)](./storage.md#getmetadata) | A Promise that resolves with the metadata for this object. If this object doesn't exist or metadata cannot be retreived, the promise is rejected. | +| [getStorage(app, bucketUrl)](./storage.md#getstorage) | Gets a [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance for the given Firebase app. | | [getStream(ref, maxDownloadSizeBytes)](./storage.md#getstream) | Downloads the data at the object's location. Raises an error event if the object is not found.This API is only available in Node. | | [list(ref, options)](./storage.md#list) | List items (files) and prefixes (folders) under this storage reference.List API is only available for Firebase Rules Version 2.GCS is a key-blob store. Firebase Storage imposes the semantic of '/' delimited folder structure. Refer to GCS's List API if you want to learn more.To adhere to Firebase Rules's Semantics, Firebase Storage does not support objects whose paths end with "/" or contain two consecutive "/"s. Firebase Storage List API will filter these unsupported objects. list() may fail if there are too many unsupported objects in the bucket. | | [listAll(ref)](./storage.md#listall) | List all items (files) and prefixes (folders) under this storage reference.This is a helper method for calling list() repeatedly until there are no more results. The default pagination size is 1000.Note: The results may not be consistent if objects are changed while this operation is running.Warning: listAll may potentially consume too many resources if there are too many results. | +| [ref(storage, url)](./storage.md#ref) | Returns a [StorageReference](./storage.storagereference.md#storagereference_interface) for the given url. | +| [ref(storageOrRef, path)](./storage.md#ref) | Returns a [StorageReference](./storage.storagereference.md#storagereference_interface) for the given path in the default bucket. | | [updateMetadata(ref, metadata)](./storage.md#updatemetadata) | Updates the metadata for this object. | | [uploadBytes(ref, data, metadata)](./storage.md#uploadbytes) | Uploads data to this object's location. The upload is not resumable. | | [uploadBytesResumable(ref, data, metadata)](./storage.md#uploadbytesresumable) | Uploads data to this object's location. The upload can be paused and resumed, and exposes progress updates. | | [uploadString(ref, value, format, metadata)](./storage.md#uploadstring) | Uploads a string to this object's location. The upload is not resumable. | -| function(storageOrRef...) | -| [ref(storageOrRef, path)](./storage.md#ref) | Returns a [StorageReference](./storage.storagereference.md#storagereference_interface) for the given path in the default bucket. | - -## Classes - -| Class | Description | -| --- | --- | -| [StorageError](./storage.storageerror.md#storageerror_class) | An error returned by the Firebase Storage SDK. | - -## Enumerations - -| Enumeration | Description | -| --- | --- | -| [StorageErrorCode](./storage.md#storageerrorcode) | Error codes that can be attached to StorageError objects. | ## Interfaces @@ -58,6 +42,7 @@ Cloud Storage for Firebase | [ListOptions](./storage.listoptions.md#listoptions_interface) | The options list() accepts. | | [ListResult](./storage.listresult.md#listresult_interface) | Result returned by list(). | | [SettableMetadata](./storage.settablemetadata.md#settablemetadata_interface) | Object metadata that can be set at any time. | +| [StorageError](./storage.storageerror.md#storageerror_interface) | An error returned by the Firebase Storage SDK. | | [StorageObserver](./storage.storageobserver.md#storageobserver_interface) | A stream observer for Firebase Storage. | | [StorageReference](./storage.storagereference.md#storagereference_interface) | Represents a reference to a Google Cloud Storage object. Developers can upload, download, and delete objects, as well as get/set object metadata. | | [UploadMetadata](./storage.uploadmetadata.md#uploadmetadata_interface) | Object metadata that can be set at upload. | @@ -79,29 +64,6 @@ Cloud Storage for Firebase | [TaskEvent](./storage.md#taskevent) | An event that is triggered on a task. | | [TaskState](./storage.md#taskstate) | Represents the current state of a running upload. | -## getStorage() - -Gets a [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance for the given Firebase app. - -Signature: - -```typescript -export declare function getStorage(app?: FirebaseApp, bucketUrl?: string): FirebaseStorage; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | Firebase app to get [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance for. | -| bucketUrl | string | The gs:// url to your Firebase Storage Bucket. If not passed, uses the app's default Storage Bucket. | - -Returns: - -[FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) - -A [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance. - ## connectStorageEmulator() Modify this [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance to communicate with the Cloud Storage emulator. @@ -127,27 +89,6 @@ export declare function connectStorageEmulator(storage: FirebaseStorage, host: s void -## ref() - -Returns a [StorageReference](./storage.storagereference.md#storagereference_interface) for the given url. - -Signature: - -```typescript -export declare function ref(storage: FirebaseStorage, url?: string): StorageReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| storage | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance. | -| url | string | URL. If empty, returns root reference. | - -Returns: - -[StorageReference](./storage.storagereference.md#storagereference_interface) - ## deleteObject() Deletes the object at this location. @@ -264,6 +205,29 @@ export declare function getMetadata(ref: StorageReference): Promise> +## getStorage() + +Gets a [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance for the given Firebase app. + +Signature: + +```typescript +export declare function getStorage(app?: FirebaseApp, bucketUrl?: string): FirebaseStorage; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | Firebase app to get [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance for. | +| bucketUrl | string | The gs:// url to your Firebase Storage Bucket. If not passed, uses the app's default Storage Bucket. | + +Returns: + +[FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) + +A [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance. + ## getStream() Downloads the data at the object's location. Raises an error event if the object is not found. @@ -346,6 +310,48 @@ Promise<[ListResult](./storage.listresult.md#listresult_interface)> A `Promise` that resolves with all the items and prefixes under the current storage reference. `prefixes` contains references to sub-directories and `items` contains references to objects in this folder. `nextPageToken` is never returned. +## ref() + +Returns a [StorageReference](./storage.storagereference.md#storagereference_interface) for the given url. + +Signature: + +```typescript +export declare function ref(storage: FirebaseStorage, url?: string): StorageReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| storage | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance. | +| url | string | URL. If empty, returns root reference. | + +Returns: + +[StorageReference](./storage.storagereference.md#storagereference_interface) + +## ref() + +Returns a [StorageReference](./storage.storagereference.md#storagereference_interface) for the given path in the default bucket. + +Signature: + +```typescript +export declare function ref(storageOrRef: FirebaseStorage | StorageReference, path?: string): StorageReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| storageOrRef | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) \| [StorageReference](./storage.storagereference.md#storagereference_interface) | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) or [StorageReference](./storage.storagereference.md#storagereference_interface). | +| path | string | | + +Returns: + +[StorageReference](./storage.storagereference.md#storagereference_interface) + ## updateMetadata() Updates the metadata for this object. @@ -442,27 +448,6 @@ Promise<[UploadResult](./storage.uploadresult.md#uploadresult_interface). | -| path | string | | - -Returns: - -[StorageReference](./storage.storagereference.md#storagereference_interface) - ## StringFormat An enumeration of the possible string formats for upload. @@ -507,44 +492,3 @@ Represents the current state of a running upload. ```typescript export declare type TaskState = 'running' | 'paused' | 'success' | 'canceled' | 'error'; ``` - -## StorageErrorCode - -Error codes that can be attached to `StorageError` objects. - -Signature: - -```typescript -export declare enum StorageErrorCode -``` - -## Enumeration Members - -| Member | Value | Description | -| --- | --- | --- | -| APP\_DELETED | "app-deleted" | | -| BUCKET\_NOT\_FOUND | "bucket-not-found" | | -| CANCELED | "canceled" | | -| CANNOT\_SLICE\_BLOB | "cannot-slice-blob" | | -| INTERNAL\_ERROR | "internal-error" | | -| INVALID\_ARGUMENT | "invalid-argument" | | -| INVALID\_ARGUMENT\_COUNT | "invalid-argument-count" | | -| INVALID\_CHECKSUM | "invalid-checksum" | | -| INVALID\_DEFAULT\_BUCKET | "invalid-default-bucket" | | -| INVALID\_EVENT\_NAME | "invalid-event-name" | | -| INVALID\_FORMAT | "invalid-format" | | -| INVALID\_ROOT\_OPERATION | "invalid-root-operation" | | -| INVALID\_URL | "invalid-url" | | -| NO\_DEFAULT\_BUCKET | "no-default-bucket" | | -| NO\_DOWNLOAD\_URL | "no-download-url" | | -| OBJECT\_NOT\_FOUND | "object-not-found" | | -| PROJECT\_NOT\_FOUND | "project-not-found" | | -| QUOTA\_EXCEEDED | "quota-exceeded" | | -| RETRY\_LIMIT\_EXCEEDED | "retry-limit-exceeded" | | -| SERVER\_FILE\_WRONG\_SIZE | "server-file-wrong-size" | | -| UNAUTHENTICATED | "unauthenticated" | | -| UNAUTHORIZED | "unauthorized" | | -| UNAUTHORIZED\_APP | "unauthorized-app" | | -| UNKNOWN | "unknown" | | -| UNSUPPORTED\_ENVIRONMENT | "unsupported-environment" | | - diff --git a/docs-devsite/storage.storageerror.md b/docs-devsite/storage.storageerror.md index 9e460e47db7..b204b37d785 100644 --- a/docs-devsite/storage.storageerror.md +++ b/docs-devsite/storage.storageerror.md @@ -9,105 +9,28 @@ overwritten. Changes should be made in the source code at https://github.com/firebase/firebase-js-sdk {% endcomment %} -# StorageError class +# StorageError interface An error returned by the Firebase Storage SDK. Signature: ```typescript -export declare class StorageError extends FirebaseError +export interface StorageError extends FirebaseError ``` Extends: [FirebaseError](./util.firebaseerror.md#firebaseerror_class) -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(code, message, status\_)](./storage.storageerror.md#storageerrorconstructor) | | Constructs a new instance of the StorageError class | - ## Properties -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [customData](./storage.storageerror.md#storageerrorcustomdata) | | { serverResponse: string \| null; } | Stores custom error data unique to the StorageError. | -| [serverResponse](./storage.storageerror.md#storageerrorserverresponse) | | null \| string | Optional response message that was added by the server. | -| [status](./storage.storageerror.md#storageerrorstatus) | | number | | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [\_codeEquals(code)](./storage.storageerror.md#storageerror_codeequals) | | Compares a StorageErrorCode against this error's code, filtering out the prefix. | - -## StorageError.(constructor) - -Constructs a new instance of the `StorageError` class - -Signature: - -```typescript -constructor(code: StorageErrorCode, message: string, status_?: number); -``` - -### Parameters - -| Parameter | Type | Description | +| Property | Type | Description | | --- | --- | --- | -| code | [StorageErrorCode](./storage.md#storageerrorcode) | A StorageErrorCode string to be prefixed with 'storage/' and added to the end of the message. | -| message | string | Error message. | -| status\_ | number | Corresponding HTTP Status Code | - -## StorageError.customData - -Stores custom error data unique to the `StorageError`. - -Signature: - -```typescript -customData: { - serverResponse: string | null; - }; -``` +| [serverResponse](./storage.storageerror.md#storageerrorserverresponse) | string \| null | A server response message for the error, if applicable. | ## StorageError.serverResponse -Optional response message that was added by the server. +A server response message for the error, if applicable. Signature: ```typescript -get serverResponse(): null | string; - -set serverResponse(serverResponse: string | null); +serverResponse: string | null; ``` - -## StorageError.status - -Signature: - -```typescript -get status(): number; - -set status(status: number); -``` - -## StorageError.\_codeEquals() - -Compares a `StorageErrorCode` against this error's code, filtering out the prefix. - -Signature: - -```typescript -_codeEquals(code: StorageErrorCode): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| code | [StorageErrorCode](./storage.md#storageerrorcode) | | - -Returns: - -boolean - diff --git a/docs-devsite/storage.storageobserver.md b/docs-devsite/storage.storageobserver.md index 583ddca7c3d..586b29c505f 100644 --- a/docs-devsite/storage.storageobserver.md +++ b/docs-devsite/storage.storageobserver.md @@ -23,7 +23,7 @@ export interface StorageObserver | Property | Type | Description | | --- | --- | --- | | [complete](./storage.storageobserver.md#storageobservercomplete) | [CompleteFn](./util.md#completefn) \| null | | -| [error](./storage.storageobserver.md#storageobservererror) | (error: [StorageError](./storage.storageerror.md#storageerror_class)) => void \| null | | +| [error](./storage.storageobserver.md#storageobservererror) | (error: [StorageError](./storage.storageerror.md#storageerror_interface)) => void \| null | | | [next](./storage.storageobserver.md#storageobservernext) | [NextFn](./util.md#nextfn)<T> \| null | | ## StorageObserver.complete diff --git a/docs-devsite/storage.uploadtask.md b/docs-devsite/storage.uploadtask.md index af4bff4088e..095c54d95ff 100644 --- a/docs-devsite/storage.uploadtask.md +++ b/docs-devsite/storage.uploadtask.md @@ -74,7 +74,7 @@ catch(onRejected: (error: StorageError) => unknown): Promise; | Parameter | Type | Description | | --- | --- | --- | -| onRejected | (error: [StorageError](./storage.storageerror.md#storageerror_class)) => unknown | | +| onRejected | (error: [StorageError](./storage.storageerror.md#storageerror_interface)) => unknown | | Returns: @@ -102,7 +102,7 @@ on(event: TaskEvent, nextOrObserver?: StorageObserver | null | --- | --- | --- | | event | [TaskEvent](./storage.md#taskevent) | The type of event to listen for. | | nextOrObserver | [StorageObserver](./storage.storageobserver.md#storageobserver_interface)<[UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface)> \| null \| ((snapshot: [UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface)) => unknown) | The next function, which gets called for each item in the event stream, or an observer object with some or all of these three properties (next, error, complete). | -| error | ((a: [StorageError](./storage.storageerror.md#storageerror_class)) => unknown) \| null | A function that gets called with a StorageError if the event stream ends due to an error. | +| error | ((a: [StorageError](./storage.storageerror.md#storageerror_interface)) => unknown) \| null | A function that gets called with a StorageError if the event stream ends due to an error. | | complete | [Unsubscribe](./util.md#unsubscribe) \| null | | Returns: @@ -247,7 +247,7 @@ then(onFulfilled?: ((snapshot: UploadTaskSnapshot) => unknown) | null, onRejecte | Parameter | Type | Description | | --- | --- | --- | | onFulfilled | ((snapshot: [UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface)) => unknown) \| null | The fulfillment callback. Promise chaining works as normal. | -| onRejected | ((error: [StorageError](./storage.storageerror.md#storageerror_class)) => unknown) \| null | The rejection callback. | +| onRejected | ((error: [StorageError](./storage.storageerror.md#storageerror_interface)) => unknown) \| null | The rejection callback. | Returns: From aa743d348856eb444a42c028345efcc5b052b9a3 Mon Sep 17 00:00:00 2001 From: Christina Holland Date: Mon, 6 Feb 2023 15:10:01 -0800 Subject: [PATCH 02/12] rm docs for now --- .github/CODEOWNERS | 3 +- .github/workflows/label-doc-changes.yml | 41 - docs-devsite/analytics.analytics.md | 35 - .../analytics.analyticscalloptions.md | 35 - docs-devsite/analytics.analyticssettings.md | 35 - docs-devsite/analytics.consentsettings.md | 79 - docs-devsite/analytics.controlparams.md | 60 - docs-devsite/analytics.customparams.md | 19 - docs-devsite/analytics.eventparams.md | 316 --- docs-devsite/analytics.gtagconfigparams.md | 134 -- docs-devsite/analytics.item.md | 278 --- docs-devsite/analytics.md | 985 -------- docs-devsite/analytics.promotion.md | 65 - docs-devsite/analytics.settingsoptions.md | 46 - docs-devsite/app-check.appcheck.md | 35 - docs-devsite/app-check.appcheckoptions.md | 46 - docs-devsite/app-check.appchecktoken.md | 44 - docs-devsite/app-check.appchecktokenresult.md | 35 - docs-devsite/app-check.customprovider.md | 43 - .../app-check.customprovideroptions.md | 35 - docs-devsite/app-check.md | 168 -- .../app-check.recaptchaenterpriseprovider.md | 43 - docs-devsite/app-check.recaptchav3provider.md | 43 - docs-devsite/app.firebaseapp.md | 91 - docs-devsite/app.firebaseappsettings.md | 46 - docs-devsite/app.firebaseoptions.md | 112 - docs-devsite/app.md | 299 --- docs-devsite/auth.actioncodeinfo.md | 58 - docs-devsite/auth.actioncodesettings.md | 95 - docs-devsite/auth.actioncodeurl.md | 121 - docs-devsite/auth.additionaluserinfo.md | 68 - docs-devsite/auth.applicationverifier.md | 59 - docs-devsite/auth.auth.md | 299 --- docs-devsite/auth.authcredential.md | 76 - docs-devsite/auth.autherror.md | 41 - docs-devsite/auth.autherrormap.md | 27 - docs-devsite/auth.authprovider.md | 35 - docs-devsite/auth.authsettings.md | 41 - docs-devsite/auth.config.md | 90 - docs-devsite/auth.confirmationresult.md | 74 - docs-devsite/auth.dependencies.md | 63 - docs-devsite/auth.emailauthcredential.md | 69 - docs-devsite/auth.emailauthprovider.md | 159 -- docs-devsite/auth.emulatorconfig.md | 70 - docs-devsite/auth.facebookauthprovider.md | 182 -- docs-devsite/auth.githubauthprovider.md | 174 -- docs-devsite/auth.googleauthprovider.md | 185 -- docs-devsite/auth.idtokenresult.md | 109 - docs-devsite/auth.md | 1939 --------------- docs-devsite/auth.multifactorassertion.md | 37 - docs-devsite/auth.multifactorerror.md | 67 - docs-devsite/auth.multifactorinfo.md | 68 - docs-devsite/auth.multifactorresolver.md | 128 - docs-devsite/auth.multifactorsession.md | 19 - docs-devsite/auth.multifactoruser.md | 161 -- docs-devsite/auth.oauthcredential.md | 105 - docs-devsite/auth.oauthcredentialoptions.md | 61 - docs-devsite/auth.oauthprovider.md | 168 -- docs-devsite/auth.parsedtoken.md | 83 - docs-devsite/auth.persistence.md | 35 - docs-devsite/auth.phoneauthcredential.md | 63 - docs-devsite/auth.phoneauthprovider.md | 256 -- .../auth.phonemultifactorassertion.md | 21 - .../auth.phonemultifactorenrollinfooptions.md | 46 - .../auth.phonemultifactorgenerator.md | 64 - docs-devsite/auth.phonemultifactorinfo.md | 36 - .../auth.phonemultifactorsignininfooptions.md | 61 - .../auth.phonesinglefactorinfooptions.md | 35 - docs-devsite/auth.popupredirectresolver.md | 19 - docs-devsite/auth.reactnativeasyncstorage.md | 89 - docs-devsite/auth.recaptchaparameters.md | 23 - docs-devsite/auth.recaptchaverifier.md | 116 - docs-devsite/auth.samlauthprovider.md | 119 - docs-devsite/auth.twitterauthprovider.md | 173 -- docs-devsite/auth.user.md | 204 -- docs-devsite/auth.usercredential.md | 59 - docs-devsite/auth.userinfo.md | 92 - docs-devsite/auth.usermetadata.md | 46 - docs-devsite/database.database.md | 46 - docs-devsite/database.databasereference.md | 68 - docs-devsite/database.datasnapshot.md | 237 -- docs-devsite/database.listenoptions.md | 35 - docs-devsite/database.md | 1393 ----------- docs-devsite/database.ondisconnect.md | 143 -- docs-devsite/database.query.md | 108 - docs-devsite/database.queryconstraint.md | 35 - docs-devsite/database.thenablereference.md | 21 - docs-devsite/database.transactionoptions.md | 35 - docs-devsite/database.transactionresult.md | 66 - docs-devsite/firestore.md | 19 - docs-devsite/firestore_.aggregatefield.md | 35 - .../firestore_.aggregatequerysnapshot.md | 70 - docs-devsite/firestore_.aggregatespec.md | 19 - docs-devsite/firestore_.bytes.md | 138 -- .../firestore_.collectionreference.md | 121 - docs-devsite/firestore_.documentchange.md | 68 - docs-devsite/firestore_.documentdata.md | 19 - docs-devsite/firestore_.documentreference.md | 142 -- docs-devsite/firestore_.documentsnapshot.md | 146 -- docs-devsite/firestore_.fieldpath.md | 72 - docs-devsite/firestore_.fieldvalue.md | 46 - docs-devsite/firestore_.firestore.md | 68 - .../firestore_.firestoredataconverter.md | 134 -- docs-devsite/firestore_.firestoreerror.md | 58 - docs-devsite/firestore_.firestoresettings.md | 96 - docs-devsite/firestore_.geopoint.md | 117 - docs-devsite/firestore_.index.md | 55 - docs-devsite/firestore_.indexconfiguration.md | 43 - docs-devsite/firestore_.indexfield.md | 73 - docs-devsite/firestore_.loadbundletask.md | 94 - .../firestore_.loadbundletaskprogress.md | 79 - docs-devsite/firestore_.md | 2103 ----------------- .../firestore_.persistencesettings.md | 35 - docs-devsite/firestore_.query.md | 125 - docs-devsite/firestore_.queryconstraint.md | 35 - .../firestore_.querydocumentsnapshot.md | 54 - docs-devsite/firestore_.querysnapshot.md | 128 - .../firestore_.snapshotlistenoptions.md | 35 - docs-devsite/firestore_.snapshotmetadata.md | 75 - docs-devsite/firestore_.snapshotoptions.md | 41 - docs-devsite/firestore_.timestamp.md | 243 -- docs-devsite/firestore_.transaction.md | 190 -- docs-devsite/firestore_.transactionoptions.md | 35 - docs-devsite/firestore_.unsubscribe.md | 19 - docs-devsite/firestore_.writebatch.md | 181 -- docs-devsite/firestore_lite.aggregatefield.md | 35 - .../firestore_lite.aggregatequerysnapshot.md | 70 - docs-devsite/firestore_lite.aggregatespec.md | 19 - docs-devsite/firestore_lite.bytes.md | 138 -- .../firestore_lite.collectionreference.md | 121 - docs-devsite/firestore_lite.documentdata.md | 19 - .../firestore_lite.documentreference.md | 142 -- .../firestore_lite.documentsnapshot.md | 125 - docs-devsite/firestore_lite.fieldpath.md | 72 - docs-devsite/firestore_lite.fieldvalue.md | 46 - docs-devsite/firestore_lite.firestore.md | 68 - .../firestore_lite.firestoredataconverter.md | 130 - docs-devsite/firestore_lite.firestoreerror.md | 58 - docs-devsite/firestore_lite.geopoint.md | 117 - docs-devsite/firestore_lite.md | 1412 ----------- docs-devsite/firestore_lite.query.md | 125 - .../firestore_lite.queryconstraint.md | 35 - .../firestore_lite.querydocumentsnapshot.md | 45 - docs-devsite/firestore_lite.querysnapshot.md | 96 - docs-devsite/firestore_lite.settings.md | 57 - docs-devsite/firestore_lite.timestamp.md | 243 -- docs-devsite/firestore_lite.transaction.md | 190 -- .../firestore_lite.transactionoptions.md | 35 - docs-devsite/firestore_lite.writebatch.md | 181 -- docs-devsite/functions.functions.md | 57 - docs-devsite/functions.functionserror.md | 47 - .../functions.httpscallableoptions.md | 35 - docs-devsite/functions.httpscallableresult.md | 35 - docs-devsite/functions.md | 160 -- docs-devsite/index.md | 30 - docs-devsite/installations.installations.md | 35 - docs-devsite/installations.md | 160 -- docs-devsite/messaging.md | 19 - docs-devsite/messaging_.fcmoptions.md | 46 - docs-devsite/messaging_.gettokenoptions.md | 46 - docs-devsite/messaging_.md | 140 -- docs-devsite/messaging_.messagepayload.md | 92 - docs-devsite/messaging_.messaging.md | 35 - .../messaging_.notificationpayload.md | 57 - docs-devsite/messaging_sw.fcmoptions.md | 46 - docs-devsite/messaging_sw.gettokenoptions.md | 46 - docs-devsite/messaging_sw.md | 113 - docs-devsite/messaging_sw.messagepayload.md | 92 - docs-devsite/messaging_sw.messaging.md | 35 - .../messaging_sw.notificationpayload.md | 57 - .../performance.firebaseperformance.md | 57 - docs-devsite/performance.md | 92 - .../performance.performancesettings.md | 46 - docs-devsite/performance.performancetrace.md | 228 -- docs-devsite/remote-config.md | 342 --- docs-devsite/remote-config.remoteconfig.md | 81 - .../remote-config.remoteconfigsettings.md | 46 - docs-devsite/remote-config.value.md | 83 - docs-devsite/storage.firebasestorage.md | 58 - docs-devsite/storage.fullmetadata.md | 135 -- docs-devsite/storage.listoptions.md | 46 - docs-devsite/storage.listresult.md | 59 - docs-devsite/storage.md | 494 ---- docs-devsite/storage.settablemetadata.md | 92 - docs-devsite/storage.storageerror.md | 36 - docs-devsite/storage.storageobserver.md | 51 - docs-devsite/storage.storagereference.md | 112 - docs-devsite/storage.uploadmetadata.md | 36 - docs-devsite/storage.uploadresult.md | 46 - docs-devsite/storage.uploadtask.md | 255 -- docs-devsite/storage.uploadtasksnapshot.md | 90 - 191 files changed, 2 insertions(+), 24302 deletions(-) delete mode 100644 .github/workflows/label-doc-changes.yml delete mode 100644 docs-devsite/analytics.analytics.md delete mode 100644 docs-devsite/analytics.analyticscalloptions.md delete mode 100644 docs-devsite/analytics.analyticssettings.md delete mode 100644 docs-devsite/analytics.consentsettings.md delete mode 100644 docs-devsite/analytics.controlparams.md delete mode 100644 docs-devsite/analytics.customparams.md delete mode 100644 docs-devsite/analytics.eventparams.md delete mode 100644 docs-devsite/analytics.gtagconfigparams.md delete mode 100644 docs-devsite/analytics.item.md delete mode 100644 docs-devsite/analytics.md delete mode 100644 docs-devsite/analytics.promotion.md delete mode 100644 docs-devsite/analytics.settingsoptions.md delete mode 100644 docs-devsite/app-check.appcheck.md delete mode 100644 docs-devsite/app-check.appcheckoptions.md delete mode 100644 docs-devsite/app-check.appchecktoken.md delete mode 100644 docs-devsite/app-check.appchecktokenresult.md delete mode 100644 docs-devsite/app-check.customprovider.md delete mode 100644 docs-devsite/app-check.customprovideroptions.md delete mode 100644 docs-devsite/app-check.md delete mode 100644 docs-devsite/app-check.recaptchaenterpriseprovider.md delete mode 100644 docs-devsite/app-check.recaptchav3provider.md delete mode 100644 docs-devsite/app.firebaseapp.md delete mode 100644 docs-devsite/app.firebaseappsettings.md delete mode 100644 docs-devsite/app.firebaseoptions.md delete mode 100644 docs-devsite/app.md delete mode 100644 docs-devsite/auth.actioncodeinfo.md delete mode 100644 docs-devsite/auth.actioncodesettings.md delete mode 100644 docs-devsite/auth.actioncodeurl.md delete mode 100644 docs-devsite/auth.additionaluserinfo.md delete mode 100644 docs-devsite/auth.applicationverifier.md delete mode 100644 docs-devsite/auth.auth.md delete mode 100644 docs-devsite/auth.authcredential.md delete mode 100644 docs-devsite/auth.autherror.md delete mode 100644 docs-devsite/auth.autherrormap.md delete mode 100644 docs-devsite/auth.authprovider.md delete mode 100644 docs-devsite/auth.authsettings.md delete mode 100644 docs-devsite/auth.config.md delete mode 100644 docs-devsite/auth.confirmationresult.md delete mode 100644 docs-devsite/auth.dependencies.md delete mode 100644 docs-devsite/auth.emailauthcredential.md delete mode 100644 docs-devsite/auth.emailauthprovider.md delete mode 100644 docs-devsite/auth.emulatorconfig.md delete mode 100644 docs-devsite/auth.facebookauthprovider.md delete mode 100644 docs-devsite/auth.githubauthprovider.md delete mode 100644 docs-devsite/auth.googleauthprovider.md delete mode 100644 docs-devsite/auth.idtokenresult.md delete mode 100644 docs-devsite/auth.md delete mode 100644 docs-devsite/auth.multifactorassertion.md delete mode 100644 docs-devsite/auth.multifactorerror.md delete mode 100644 docs-devsite/auth.multifactorinfo.md delete mode 100644 docs-devsite/auth.multifactorresolver.md delete mode 100644 docs-devsite/auth.multifactorsession.md delete mode 100644 docs-devsite/auth.multifactoruser.md delete mode 100644 docs-devsite/auth.oauthcredential.md delete mode 100644 docs-devsite/auth.oauthcredentialoptions.md delete mode 100644 docs-devsite/auth.oauthprovider.md delete mode 100644 docs-devsite/auth.parsedtoken.md delete mode 100644 docs-devsite/auth.persistence.md delete mode 100644 docs-devsite/auth.phoneauthcredential.md delete mode 100644 docs-devsite/auth.phoneauthprovider.md delete mode 100644 docs-devsite/auth.phonemultifactorassertion.md delete mode 100644 docs-devsite/auth.phonemultifactorenrollinfooptions.md delete mode 100644 docs-devsite/auth.phonemultifactorgenerator.md delete mode 100644 docs-devsite/auth.phonemultifactorinfo.md delete mode 100644 docs-devsite/auth.phonemultifactorsignininfooptions.md delete mode 100644 docs-devsite/auth.phonesinglefactorinfooptions.md delete mode 100644 docs-devsite/auth.popupredirectresolver.md delete mode 100644 docs-devsite/auth.reactnativeasyncstorage.md delete mode 100644 docs-devsite/auth.recaptchaparameters.md delete mode 100644 docs-devsite/auth.recaptchaverifier.md delete mode 100644 docs-devsite/auth.samlauthprovider.md delete mode 100644 docs-devsite/auth.twitterauthprovider.md delete mode 100644 docs-devsite/auth.user.md delete mode 100644 docs-devsite/auth.usercredential.md delete mode 100644 docs-devsite/auth.userinfo.md delete mode 100644 docs-devsite/auth.usermetadata.md delete mode 100644 docs-devsite/database.database.md delete mode 100644 docs-devsite/database.databasereference.md delete mode 100644 docs-devsite/database.datasnapshot.md delete mode 100644 docs-devsite/database.listenoptions.md delete mode 100644 docs-devsite/database.md delete mode 100644 docs-devsite/database.ondisconnect.md delete mode 100644 docs-devsite/database.query.md delete mode 100644 docs-devsite/database.queryconstraint.md delete mode 100644 docs-devsite/database.thenablereference.md delete mode 100644 docs-devsite/database.transactionoptions.md delete mode 100644 docs-devsite/database.transactionresult.md delete mode 100644 docs-devsite/firestore.md delete mode 100644 docs-devsite/firestore_.aggregatefield.md delete mode 100644 docs-devsite/firestore_.aggregatequerysnapshot.md delete mode 100644 docs-devsite/firestore_.aggregatespec.md delete mode 100644 docs-devsite/firestore_.bytes.md delete mode 100644 docs-devsite/firestore_.collectionreference.md delete mode 100644 docs-devsite/firestore_.documentchange.md delete mode 100644 docs-devsite/firestore_.documentdata.md delete mode 100644 docs-devsite/firestore_.documentreference.md delete mode 100644 docs-devsite/firestore_.documentsnapshot.md delete mode 100644 docs-devsite/firestore_.fieldpath.md delete mode 100644 docs-devsite/firestore_.fieldvalue.md delete mode 100644 docs-devsite/firestore_.firestore.md delete mode 100644 docs-devsite/firestore_.firestoredataconverter.md delete mode 100644 docs-devsite/firestore_.firestoreerror.md delete mode 100644 docs-devsite/firestore_.firestoresettings.md delete mode 100644 docs-devsite/firestore_.geopoint.md delete mode 100644 docs-devsite/firestore_.index.md delete mode 100644 docs-devsite/firestore_.indexconfiguration.md delete mode 100644 docs-devsite/firestore_.indexfield.md delete mode 100644 docs-devsite/firestore_.loadbundletask.md delete mode 100644 docs-devsite/firestore_.loadbundletaskprogress.md delete mode 100644 docs-devsite/firestore_.md delete mode 100644 docs-devsite/firestore_.persistencesettings.md delete mode 100644 docs-devsite/firestore_.query.md delete mode 100644 docs-devsite/firestore_.queryconstraint.md delete mode 100644 docs-devsite/firestore_.querydocumentsnapshot.md delete mode 100644 docs-devsite/firestore_.querysnapshot.md delete mode 100644 docs-devsite/firestore_.snapshotlistenoptions.md delete mode 100644 docs-devsite/firestore_.snapshotmetadata.md delete mode 100644 docs-devsite/firestore_.snapshotoptions.md delete mode 100644 docs-devsite/firestore_.timestamp.md delete mode 100644 docs-devsite/firestore_.transaction.md delete mode 100644 docs-devsite/firestore_.transactionoptions.md delete mode 100644 docs-devsite/firestore_.unsubscribe.md delete mode 100644 docs-devsite/firestore_.writebatch.md delete mode 100644 docs-devsite/firestore_lite.aggregatefield.md delete mode 100644 docs-devsite/firestore_lite.aggregatequerysnapshot.md delete mode 100644 docs-devsite/firestore_lite.aggregatespec.md delete mode 100644 docs-devsite/firestore_lite.bytes.md delete mode 100644 docs-devsite/firestore_lite.collectionreference.md delete mode 100644 docs-devsite/firestore_lite.documentdata.md delete mode 100644 docs-devsite/firestore_lite.documentreference.md delete mode 100644 docs-devsite/firestore_lite.documentsnapshot.md delete mode 100644 docs-devsite/firestore_lite.fieldpath.md delete mode 100644 docs-devsite/firestore_lite.fieldvalue.md delete mode 100644 docs-devsite/firestore_lite.firestore.md delete mode 100644 docs-devsite/firestore_lite.firestoredataconverter.md delete mode 100644 docs-devsite/firestore_lite.firestoreerror.md delete mode 100644 docs-devsite/firestore_lite.geopoint.md delete mode 100644 docs-devsite/firestore_lite.md delete mode 100644 docs-devsite/firestore_lite.query.md delete mode 100644 docs-devsite/firestore_lite.queryconstraint.md delete mode 100644 docs-devsite/firestore_lite.querydocumentsnapshot.md delete mode 100644 docs-devsite/firestore_lite.querysnapshot.md delete mode 100644 docs-devsite/firestore_lite.settings.md delete mode 100644 docs-devsite/firestore_lite.timestamp.md delete mode 100644 docs-devsite/firestore_lite.transaction.md delete mode 100644 docs-devsite/firestore_lite.transactionoptions.md delete mode 100644 docs-devsite/firestore_lite.writebatch.md delete mode 100644 docs-devsite/functions.functions.md delete mode 100644 docs-devsite/functions.functionserror.md delete mode 100644 docs-devsite/functions.httpscallableoptions.md delete mode 100644 docs-devsite/functions.httpscallableresult.md delete mode 100644 docs-devsite/functions.md delete mode 100644 docs-devsite/index.md delete mode 100644 docs-devsite/installations.installations.md delete mode 100644 docs-devsite/installations.md delete mode 100644 docs-devsite/messaging.md delete mode 100644 docs-devsite/messaging_.fcmoptions.md delete mode 100644 docs-devsite/messaging_.gettokenoptions.md delete mode 100644 docs-devsite/messaging_.md delete mode 100644 docs-devsite/messaging_.messagepayload.md delete mode 100644 docs-devsite/messaging_.messaging.md delete mode 100644 docs-devsite/messaging_.notificationpayload.md delete mode 100644 docs-devsite/messaging_sw.fcmoptions.md delete mode 100644 docs-devsite/messaging_sw.gettokenoptions.md delete mode 100644 docs-devsite/messaging_sw.md delete mode 100644 docs-devsite/messaging_sw.messagepayload.md delete mode 100644 docs-devsite/messaging_sw.messaging.md delete mode 100644 docs-devsite/messaging_sw.notificationpayload.md delete mode 100644 docs-devsite/performance.firebaseperformance.md delete mode 100644 docs-devsite/performance.md delete mode 100644 docs-devsite/performance.performancesettings.md delete mode 100644 docs-devsite/performance.performancetrace.md delete mode 100644 docs-devsite/remote-config.md delete mode 100644 docs-devsite/remote-config.remoteconfig.md delete mode 100644 docs-devsite/remote-config.remoteconfigsettings.md delete mode 100644 docs-devsite/remote-config.value.md delete mode 100644 docs-devsite/storage.firebasestorage.md delete mode 100644 docs-devsite/storage.fullmetadata.md delete mode 100644 docs-devsite/storage.listoptions.md delete mode 100644 docs-devsite/storage.listresult.md delete mode 100644 docs-devsite/storage.md delete mode 100644 docs-devsite/storage.settablemetadata.md delete mode 100644 docs-devsite/storage.storageerror.md delete mode 100644 docs-devsite/storage.storageobserver.md delete mode 100644 docs-devsite/storage.storagereference.md delete mode 100644 docs-devsite/storage.uploadmetadata.md delete mode 100644 docs-devsite/storage.uploadresult.md delete mode 100644 docs-devsite/storage.uploadtask.md delete mode 100644 docs-devsite/storage.uploadtasksnapshot.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index a340ff25229..7fc0473cbfa 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -96,6 +96,7 @@ packages/app-check-interop-types @hsubox76 @firebase/jssdk-global-approvers # Documentation Changes packages/firebase/index.d.ts @egilmorez @firebase/jssdk-global-approvers scripts/docgen/content-sources/ @egilmorez @firebase/jssdk-global-approvers +docs-devsite/ # Changeset -.changeset @egilmorez @firebase/jssdk-changeset-approvers @firebase/firestore-js-team @firebase/jssdk-global-approvers +.changeset @egilmorez @firebase/jssdk-changeset-approvers @firebase/firestore-js-team @firebase/jssdk-global-approvers \ No newline at end of file diff --git a/.github/workflows/label-doc-changes.yml b/.github/workflows/label-doc-changes.yml deleted file mode 100644 index 156fa49d975..00000000000 --- a/.github/workflows/label-doc-changes.yml +++ /dev/null @@ -1,41 +0,0 @@ -name: Label doc changes - -on: pull_request - -env: - GITHUB_PULL_REQUEST_HEAD_SHA: ${{ github.event.pull_request.head.sha }} - GITHUB_PULL_REQUEST_BASE_SHA: ${{ github.event.pull_request.base.sha }} - -jobs: - check_doc_changes: - name: Check if docs are being changed - runs-on: ubuntu-latest - - steps: - - name: Checkout Repo - uses: actions/checkout@master - with: - # This makes Actions fetch all Git history so check_changeset script can diff properly. - fetch-depth: 0 - - name: Set up Node (14) - uses: actions/setup-node@v2 - with: - node-version: 14.x - - name: Yarn install - run: yarn - - name: Run detect doc changes script - run: yarn ts-node-script scripts/ci/detect-doc-changes.ts - id: check-doc-changes - - name: Print if doc changed output - run: echo "${{steps.check-doc-changes.outputs.DOC_CHANGED}}" - - name: Add label if there are doc changes - uses: actions-ecosystem/action-add-labels@v1.1.3 - if: ${{steps.check-doc-changes.outputs.DOC_CHANGED == 'true'}} - with: - labels: doc-changes - github_token: ${{ github.token }} - - name: assign techwriters to PR - if: ${{steps.check-doc-changes.outputs.DOC_CHANGED == 'true'}} - uses: kentaro-m/auto-assign-action@v1.2.1 - with: - configuration-path: ".github/auto_assign.yml" diff --git a/docs-devsite/analytics.analytics.md b/docs-devsite/analytics.analytics.md deleted file mode 100644 index dcf0038f2d9..00000000000 --- a/docs-devsite/analytics.analytics.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Analytics interface -An instance of Firebase Analytics. - -Signature: - -```typescript -export interface Analytics -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [app](./analytics.analytics.md#analyticsapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this [Analytics](./analytics.analytics.md#analytics_interface) instance is associated with. | - -## Analytics.app - -The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this [Analytics](./analytics.analytics.md#analytics_interface) instance is associated with. - -Signature: - -```typescript -app: FirebaseApp; -``` diff --git a/docs-devsite/analytics.analyticscalloptions.md b/docs-devsite/analytics.analyticscalloptions.md deleted file mode 100644 index d89863bcfa6..00000000000 --- a/docs-devsite/analytics.analyticscalloptions.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AnalyticsCallOptions interface -Additional options that can be passed to Analytics method calls such as `logEvent`, etc. - -Signature: - -```typescript -export interface AnalyticsCallOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [global](./analytics.analyticscalloptions.md#analyticscalloptionsglobal) | boolean | If true, this config or event call applies globally to all Google Analytics properties on the page. | - -## AnalyticsCallOptions.global - -If true, this config or event call applies globally to all Google Analytics properties on the page. - -Signature: - -```typescript -global: boolean; -``` diff --git a/docs-devsite/analytics.analyticssettings.md b/docs-devsite/analytics.analyticssettings.md deleted file mode 100644 index 3ee67d8456d..00000000000 --- a/docs-devsite/analytics.analyticssettings.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AnalyticsSettings interface -[Analytics](./analytics.analytics.md#analytics_interface) instance initialization options. - -Signature: - -```typescript -export interface AnalyticsSettings -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [config](./analytics.analyticssettings.md#analyticssettingsconfig) | [GtagConfigParams](./analytics.gtagconfigparams.md#gtagconfigparams_interface) \| [EventParams](./analytics.eventparams.md#eventparams_interface) | Params to be passed in the initial gtag config call during Firebase Analytics initialization. | - -## AnalyticsSettings.config - -Params to be passed in the initial `gtag` config call during Firebase Analytics initialization. - -Signature: - -```typescript -config?: GtagConfigParams | EventParams; -``` diff --git a/docs-devsite/analytics.consentsettings.md b/docs-devsite/analytics.consentsettings.md deleted file mode 100644 index 975d51d8bc6..00000000000 --- a/docs-devsite/analytics.consentsettings.md +++ /dev/null @@ -1,79 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ConsentSettings interface -Consent status settings for each consent type. For more information, see [the GA4 reference documentation for consent state and consent types](https://developers.google.com/tag-platform/tag-manager/templates/consent-apis). - -Signature: - -```typescript -export interface ConsentSettings -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [ad\_storage](./analytics.consentsettings.md#consentsettingsad_storage) | [ConsentStatusString](./analytics.md#consentstatusstring) | Enables storage, such as cookies, related to advertising | -| [analytics\_storage](./analytics.consentsettings.md#consentsettingsanalytics_storage) | [ConsentStatusString](./analytics.md#consentstatusstring) | Enables storage, such as cookies, related to analytics (for example, visit duration) | -| [functionality\_storage](./analytics.consentsettings.md#consentsettingsfunctionality_storage) | [ConsentStatusString](./analytics.md#consentstatusstring) | Enables storage that supports the functionality of the website or app such as language settings | -| [personalization\_storage](./analytics.consentsettings.md#consentsettingspersonalization_storage) | [ConsentStatusString](./analytics.md#consentstatusstring) | Enables storage related to personalization such as video recommendations | -| [security\_storage](./analytics.consentsettings.md#consentsettingssecurity_storage) | [ConsentStatusString](./analytics.md#consentstatusstring) | Enables storage related to security such as authentication functionality, fraud prevention, and other user protection. | - -## ConsentSettings.ad\_storage - -Enables storage, such as cookies, related to advertising - -Signature: - -```typescript -ad_storage?: ConsentStatusString; -``` - -## ConsentSettings.analytics\_storage - -Enables storage, such as cookies, related to analytics (for example, visit duration) - -Signature: - -```typescript -analytics_storage?: ConsentStatusString; -``` - -## ConsentSettings.functionality\_storage - -Enables storage that supports the functionality of the website or app such as language settings - -Signature: - -```typescript -functionality_storage?: ConsentStatusString; -``` - -## ConsentSettings.personalization\_storage - -Enables storage related to personalization such as video recommendations - -Signature: - -```typescript -personalization_storage?: ConsentStatusString; -``` - -## ConsentSettings.security\_storage - -Enables storage related to security such as authentication functionality, fraud prevention, and other user protection. - -Signature: - -```typescript -security_storage?: ConsentStatusString; -``` diff --git a/docs-devsite/analytics.controlparams.md b/docs-devsite/analytics.controlparams.md deleted file mode 100644 index d7dfea1460c..00000000000 --- a/docs-devsite/analytics.controlparams.md +++ /dev/null @@ -1,60 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ControlParams interface -Standard `gtag.js` control parameters. For more information, see [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export interface ControlParams -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [event\_callback](./analytics.controlparams.md#controlparamsevent_callback) | () => void | | -| [event\_timeout](./analytics.controlparams.md#controlparamsevent_timeout) | number | | -| [groups](./analytics.controlparams.md#controlparamsgroups) | string \| string\[\] | | -| [send\_to](./analytics.controlparams.md#controlparamssend_to) | string \| string\[\] | | - -## ControlParams.event\_callback - -Signature: - -```typescript -event_callback?: () => void; -``` - -## ControlParams.event\_timeout - -Signature: - -```typescript -event_timeout?: number; -``` - -## ControlParams.groups - -Signature: - -```typescript -groups?: string | string[]; -``` - -## ControlParams.send\_to - -Signature: - -```typescript -send_to?: string | string[]; -``` diff --git a/docs-devsite/analytics.customparams.md b/docs-devsite/analytics.customparams.md deleted file mode 100644 index 37ac6964477..00000000000 --- a/docs-devsite/analytics.customparams.md +++ /dev/null @@ -1,19 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# CustomParams interface -Any custom params the user may pass to `gtag`. - -Signature: - -```typescript -export interface CustomParams -``` diff --git a/docs-devsite/analytics.eventparams.md b/docs-devsite/analytics.eventparams.md deleted file mode 100644 index 266b8d3e85e..00000000000 --- a/docs-devsite/analytics.eventparams.md +++ /dev/null @@ -1,316 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# EventParams interface -Standard `gtag.js` event parameters. For more information, see [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export interface EventParams -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [affiliation](./analytics.eventparams.md#eventparamsaffiliation) | string | | -| [checkout\_option](./analytics.eventparams.md#eventparamscheckout_option) | string | | -| [checkout\_step](./analytics.eventparams.md#eventparamscheckout_step) | number | | -| [content\_type](./analytics.eventparams.md#eventparamscontent_type) | string | | -| [coupon](./analytics.eventparams.md#eventparamscoupon) | string | | -| [currency](./analytics.eventparams.md#eventparamscurrency) | string | | -| [description](./analytics.eventparams.md#eventparamsdescription) | string | | -| [event\_category](./analytics.eventparams.md#eventparamsevent_category) | string | | -| [event\_label](./analytics.eventparams.md#eventparamsevent_label) | string | | -| [fatal](./analytics.eventparams.md#eventparamsfatal) | boolean | | -| [firebase\_screen\_class](./analytics.eventparams.md#eventparamsfirebase_screen_class) | string | Firebase-specific. Use to log a screen_class to Firebase Analytics. | -| [firebase\_screen](./analytics.eventparams.md#eventparamsfirebase_screen) | string | Firebase-specific. Use to log a screen_name to Firebase Analytics. | -| [item\_id](./analytics.eventparams.md#eventparamsitem_id) | string | | -| [item\_list\_id](./analytics.eventparams.md#eventparamsitem_list_id) | string | | -| [item\_list\_name](./analytics.eventparams.md#eventparamsitem_list_name) | string | | -| [items](./analytics.eventparams.md#eventparamsitems) | [Item](./analytics.item.md#item_interface)\[\] | | -| [method](./analytics.eventparams.md#eventparamsmethod) | string | | -| [number](./analytics.eventparams.md#eventparamsnumber) | string | | -| [page\_location](./analytics.eventparams.md#eventparamspage_location) | string | | -| [page\_path](./analytics.eventparams.md#eventparamspage_path) | string | | -| [page\_title](./analytics.eventparams.md#eventparamspage_title) | string | | -| [payment\_type](./analytics.eventparams.md#eventparamspayment_type) | string | | -| [promotion\_id](./analytics.eventparams.md#eventparamspromotion_id) | string | | -| [promotion\_name](./analytics.eventparams.md#eventparamspromotion_name) | string | | -| [promotions](./analytics.eventparams.md#eventparamspromotions) | [Promotion](./analytics.promotion.md#promotion_interface)\[\] | | -| [screen\_name](./analytics.eventparams.md#eventparamsscreen_name) | string | | -| [search\_term](./analytics.eventparams.md#eventparamssearch_term) | string | | -| [shipping\_tier](./analytics.eventparams.md#eventparamsshipping_tier) | string | | -| [shipping](./analytics.eventparams.md#eventparamsshipping) | [Currency](./analytics.md#currency) | | -| [tax](./analytics.eventparams.md#eventparamstax) | [Currency](./analytics.md#currency) | | -| [transaction\_id](./analytics.eventparams.md#eventparamstransaction_id) | string | | -| [value](./analytics.eventparams.md#eventparamsvalue) | number | | - -## EventParams.affiliation - -Signature: - -```typescript -affiliation?: string; -``` - -## EventParams.checkout\_option - -Signature: - -```typescript -checkout_option?: string; -``` - -## EventParams.checkout\_step - -Signature: - -```typescript -checkout_step?: number; -``` - -## EventParams.content\_type - -Signature: - -```typescript -content_type?: string; -``` - -## EventParams.coupon - -Signature: - -```typescript -coupon?: string; -``` - -## EventParams.currency - -Signature: - -```typescript -currency?: string; -``` - -## EventParams.description - -Signature: - -```typescript -description?: string; -``` - -## EventParams.event\_category - -Signature: - -```typescript -event_category?: string; -``` - -## EventParams.event\_label - -Signature: - -```typescript -event_label?: string; -``` - -## EventParams.fatal - -Signature: - -```typescript -fatal?: boolean; -``` - -## EventParams.firebase\_screen\_class - -Firebase-specific. Use to log a `screen_class` to Firebase Analytics. - -Signature: - -```typescript -firebase_screen_class?: string; -``` - -## EventParams.firebase\_screen - -Firebase-specific. Use to log a `screen_name` to Firebase Analytics. - -Signature: - -```typescript -firebase_screen?: string; -``` - -## EventParams.item\_id - -Signature: - -```typescript -item_id?: string; -``` - -## EventParams.item\_list\_id - -Signature: - -```typescript -item_list_id?: string; -``` - -## EventParams.item\_list\_name - -Signature: - -```typescript -item_list_name?: string; -``` - -## EventParams.items - -Signature: - -```typescript -items?: Item[]; -``` - -## EventParams.method - -Signature: - -```typescript -method?: string; -``` - -## EventParams.number - -Signature: - -```typescript -number?: string; -``` - -## EventParams.page\_location - -Signature: - -```typescript -page_location?: string; -``` - -## EventParams.page\_path - -Signature: - -```typescript -page_path?: string; -``` - -## EventParams.page\_title - -Signature: - -```typescript -page_title?: string; -``` - -## EventParams.payment\_type - -Signature: - -```typescript -payment_type?: string; -``` - -## EventParams.promotion\_id - -Signature: - -```typescript -promotion_id?: string; -``` - -## EventParams.promotion\_name - -Signature: - -```typescript -promotion_name?: string; -``` - -## EventParams.promotions - -Signature: - -```typescript -promotions?: Promotion[]; -``` - -## EventParams.screen\_name - -Signature: - -```typescript -screen_name?: string; -``` - -## EventParams.search\_term - -Signature: - -```typescript -search_term?: string; -``` - -## EventParams.shipping\_tier - -Signature: - -```typescript -shipping_tier?: string; -``` - -## EventParams.shipping - -Signature: - -```typescript -shipping?: Currency; -``` - -## EventParams.tax - -Signature: - -```typescript -tax?: Currency; -``` - -## EventParams.transaction\_id - -Signature: - -```typescript -transaction_id?: string; -``` - -## EventParams.value - -Signature: - -```typescript -value?: number; -``` diff --git a/docs-devsite/analytics.gtagconfigparams.md b/docs-devsite/analytics.gtagconfigparams.md deleted file mode 100644 index f5138b8b65e..00000000000 --- a/docs-devsite/analytics.gtagconfigparams.md +++ /dev/null @@ -1,134 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# GtagConfigParams interface -A set of common Google Analytics config settings recognized by `gtag.js`. - -Signature: - -```typescript -export interface GtagConfigParams -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [allow\_ad\_personalization\_signals](./analytics.gtagconfigparams.md#gtagconfigparamsallow_ad_personalization_signals) | boolean | If set to false, disables all advertising personalization with gtag.js. See [Disable advertising features](https://developers.google.com/analytics/devguides/collection/ga4/display-features) | -| [allow\_google\_signals](./analytics.gtagconfigparams.md#gtagconfigparamsallow_google_signals) | boolean | If set to false, disables all advertising features with gtag.js. See [Disable advertising features](https://developers.google.com/analytics/devguides/collection/ga4/display-features) | -| [cookie\_domain](./analytics.gtagconfigparams.md#gtagconfigparamscookie_domain) | string | Defaults to auto. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) | -| [cookie\_expires](./analytics.gtagconfigparams.md#gtagconfigparamscookie_expires) | number | Defaults to 63072000 (two years, in seconds). See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) | -| [cookie\_flags](./analytics.gtagconfigparams.md#gtagconfigparamscookie_flags) | string | Appends additional flags to the cookie when set. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) | -| [cookie\_prefix](./analytics.gtagconfigparams.md#gtagconfigparamscookie_prefix) | string | Defaults to _ga. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) | -| [cookie\_update](./analytics.gtagconfigparams.md#gtagconfigparamscookie_update) | boolean | If set to true, will update cookies on each page load. Defaults to true. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) | -| [page\_location](./analytics.gtagconfigparams.md#gtagconfigparamspage_location) | string | The URL of the page. See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view) | -| [page\_title](./analytics.gtagconfigparams.md#gtagconfigparamspage_title) | string | The title of the page. See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view) | -| [send\_page\_view](./analytics.gtagconfigparams.md#gtagconfigparamssend_page_view) | boolean | Whether or not a page view should be sent. If set to true (default), a page view is automatically sent upon initialization of analytics. See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view) | - -## GtagConfigParams.allow\_ad\_personalization\_signals - -If set to false, disables all advertising personalization with `gtag.js`. See [Disable advertising features](https://developers.google.com/analytics/devguides/collection/ga4/display-features) - -Signature: - -```typescript -'allow_ad_personalization_signals'?: boolean; -``` - -## GtagConfigParams.allow\_google\_signals - -If set to false, disables all advertising features with `gtag.js`. See [Disable advertising features](https://developers.google.com/analytics/devguides/collection/ga4/display-features) - -Signature: - -```typescript -'allow_google_signals'?: boolean; -``` - -## GtagConfigParams.cookie\_domain - -Defaults to `auto`. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) - -Signature: - -```typescript -'cookie_domain'?: string; -``` - -## GtagConfigParams.cookie\_expires - -Defaults to 63072000 (two years, in seconds). See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) - -Signature: - -```typescript -'cookie_expires'?: number; -``` - -## GtagConfigParams.cookie\_flags - -Appends additional flags to the cookie when set. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) - -Signature: - -```typescript -'cookie_flags'?: string; -``` - -## GtagConfigParams.cookie\_prefix - -Defaults to `_ga`. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) - -Signature: - -```typescript -'cookie_prefix'?: string; -``` - -## GtagConfigParams.cookie\_update - -If set to true, will update cookies on each page load. Defaults to true. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) - -Signature: - -```typescript -'cookie_update'?: boolean; -``` - -## GtagConfigParams.page\_location - -The URL of the page. See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view) - -Signature: - -```typescript -'page_location'?: string; -``` - -## GtagConfigParams.page\_title - -The title of the page. See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view) - -Signature: - -```typescript -'page_title'?: string; -``` - -## GtagConfigParams.send\_page\_view - -Whether or not a page view should be sent. If set to true (default), a page view is automatically sent upon initialization of analytics. See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view) - -Signature: - -```typescript -'send_page_view'?: boolean; -``` diff --git a/docs-devsite/analytics.item.md b/docs-devsite/analytics.item.md deleted file mode 100644 index 5c853918edb..00000000000 --- a/docs-devsite/analytics.item.md +++ /dev/null @@ -1,278 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Item interface -Standard Google Analytics `Item` type. - -Signature: - -```typescript -export interface Item -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [affiliation](./analytics.item.md#itemaffiliation) | string | | -| [brand](./analytics.item.md#itembrand) | string | | -| [category](./analytics.item.md#itemcategory) | string | | -| [coupon](./analytics.item.md#itemcoupon) | string | | -| [creative\_name](./analytics.item.md#itemcreative_name) | string | | -| [creative\_slot](./analytics.item.md#itemcreative_slot) | string | | -| [discount](./analytics.item.md#itemdiscount) | [Currency](./analytics.md#currency) | | -| [id](./analytics.item.md#itemid) | string | | -| [index](./analytics.item.md#itemindex) | number | | -| [item\_brand](./analytics.item.md#itemitem_brand) | string | | -| [item\_category](./analytics.item.md#itemitem_category) | string | | -| [item\_category2](./analytics.item.md#itemitem_category2) | string | | -| [item\_category3](./analytics.item.md#itemitem_category3) | string | | -| [item\_category4](./analytics.item.md#itemitem_category4) | string | | -| [item\_category5](./analytics.item.md#itemitem_category5) | string | | -| [item\_id](./analytics.item.md#itemitem_id) | string | | -| [item\_list\_id](./analytics.item.md#itemitem_list_id) | string | | -| [item\_list\_name](./analytics.item.md#itemitem_list_name) | string | | -| [item\_name](./analytics.item.md#itemitem_name) | string | | -| [item\_variant](./analytics.item.md#itemitem_variant) | string | | -| [location\_id](./analytics.item.md#itemlocation_id) | string | | -| [name](./analytics.item.md#itemname) | string | | -| [price](./analytics.item.md#itemprice) | [Currency](./analytics.md#currency) | | -| [promotion\_id](./analytics.item.md#itempromotion_id) | string | | -| [promotion\_name](./analytics.item.md#itempromotion_name) | string | | -| [quantity](./analytics.item.md#itemquantity) | number | | - -## Item.affiliation - -Signature: - -```typescript -affiliation?: string; -``` - -## Item.brand - -> Warning: This API is now obsolete. -> -> Use item\_brand instead. -> - -Signature: - -```typescript -brand?: string; -``` - -## Item.category - -> Warning: This API is now obsolete. -> -> Use item\_category instead. -> - -Signature: - -```typescript -category?: string; -``` - -## Item.coupon - -Signature: - -```typescript -coupon?: string; -``` - -## Item.creative\_name - -Signature: - -```typescript -creative_name?: string; -``` - -## Item.creative\_slot - -Signature: - -```typescript -creative_slot?: string; -``` - -## Item.discount - -Signature: - -```typescript -discount?: Currency; -``` - -## Item.id - -> Warning: This API is now obsolete. -> -> Use item\_id instead. -> - -Signature: - -```typescript -id?: string; -``` - -## Item.index - -Signature: - -```typescript -index?: number; -``` - -## Item.item\_brand - -Signature: - -```typescript -item_brand?: string; -``` - -## Item.item\_category - -Signature: - -```typescript -item_category?: string; -``` - -## Item.item\_category2 - -Signature: - -```typescript -item_category2?: string; -``` - -## Item.item\_category3 - -Signature: - -```typescript -item_category3?: string; -``` - -## Item.item\_category4 - -Signature: - -```typescript -item_category4?: string; -``` - -## Item.item\_category5 - -Signature: - -```typescript -item_category5?: string; -``` - -## Item.item\_id - -Signature: - -```typescript -item_id?: string; -``` - -## Item.item\_list\_id - -Signature: - -```typescript -item_list_id?: string; -``` - -## Item.item\_list\_name - -Signature: - -```typescript -item_list_name?: string; -``` - -## Item.item\_name - -Signature: - -```typescript -item_name?: string; -``` - -## Item.item\_variant - -Signature: - -```typescript -item_variant?: string; -``` - -## Item.location\_id - -Signature: - -```typescript -location_id?: string; -``` - -## Item.name - -> Warning: This API is now obsolete. -> -> Use item\_name instead. -> - -Signature: - -```typescript -name?: string; -``` - -## Item.price - -Signature: - -```typescript -price?: Currency; -``` - -## Item.promotion\_id - -Signature: - -```typescript -promotion_id?: string; -``` - -## Item.promotion\_name - -Signature: - -```typescript -promotion_name?: string; -``` - -## Item.quantity - -Signature: - -```typescript -quantity?: number; -``` diff --git a/docs-devsite/analytics.md b/docs-devsite/analytics.md deleted file mode 100644 index aaaf2d29863..00000000000 --- a/docs-devsite/analytics.md +++ /dev/null @@ -1,985 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# analytics package -Firebase Analytics - -## Functions - -| Function | Description | -| --- | --- | -| [getAnalytics(app)](./analytics.md#getanalytics) | Returns an [Analytics](./analytics.analytics.md#analytics_interface) instance for the given app. | -| [initializeAnalytics(app, options)](./analytics.md#initializeanalytics) | Returns an [Analytics](./analytics.analytics.md#analytics_interface) instance for the given app. | -| [isSupported()](./analytics.md#issupported) | This is a public static method provided to users that wraps four different checks:1. Check if it's not a browser extension environment. 2. Check if cookies are enabled in current browser. 3. Check if IndexedDB is supported by the browser environment. 4. Check if the current browser context is valid for using IndexedDB.open(). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.See [Track Screenviews](https://firebase.google.com/docs/analytics/screenviews). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.See [Measure exceptions](https://developers.google.com/analytics/devguides/collection/ga4/exceptions). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view). | -| [setAnalyticsCollectionEnabled(analyticsInstance, enabled)](./analytics.md#setanalyticscollectionenabled) | Sets whether Google Analytics collection is enabled for this app on this device. Sets global window['ga-disable-analyticsId'] = true; | -| [setConsent(consentSettings)](./analytics.md#setconsent) | Sets the applicable end user consent state for this web app across all gtag references once Firebase Analytics is initialized.Use the [ConsentSettings](./analytics.consentsettings.md#consentsettings_interface) to specify individual consent type values. By default consent types are set to "granted". | -| [setCurrentScreen(analyticsInstance, screenName, options)](./analytics.md#setcurrentscreen) | Use gtag config command to set screen_name. | -| [setDefaultEventParameters(customParams)](./analytics.md#setdefaulteventparameters) | Adds data that will be set on every event logged from the SDK, including automatic ones. With gtag's "set" command, the values passed persist on the current page and are passed with all subsequent events. | -| [settings(options)](./analytics.md#settings) | Configures Firebase Analytics to use custom gtag or dataLayer names. Intended to be used if gtag.js script has been installed on this page independently of Firebase Analytics, and is using non-default names for either the gtag function or for dataLayer. Must be called before calling getAnalytics() or it won't have any effect. | -| [setUserId(analyticsInstance, id, options)](./analytics.md#setuserid) | Use gtag config command to set user_id. | -| [setUserProperties(analyticsInstance, properties, options)](./analytics.md#setuserproperties) | Use gtag config command to set all params specified. | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [Analytics](./analytics.analytics.md#analytics_interface) | An instance of Firebase Analytics. | -| [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | Additional options that can be passed to Analytics method calls such as logEvent, etc. | -| [AnalyticsSettings](./analytics.analyticssettings.md#analyticssettings_interface) | [Analytics](./analytics.analytics.md#analytics_interface) instance initialization options. | -| [ConsentSettings](./analytics.consentsettings.md#consentsettings_interface) | Consent status settings for each consent type. For more information, see [the GA4 reference documentation for consent state and consent types](https://developers.google.com/tag-platform/tag-manager/templates/consent-apis). | -| [ControlParams](./analytics.controlparams.md#controlparams_interface) | Standard gtag.js control parameters. For more information, see [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [CustomParams](./analytics.customparams.md#customparams_interface) | Any custom params the user may pass to gtag. | -| [EventParams](./analytics.eventparams.md#eventparams_interface) | Standard gtag.js event parameters. For more information, see [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [GtagConfigParams](./analytics.gtagconfigparams.md#gtagconfigparams_interface) | A set of common Google Analytics config settings recognized by gtag.js. | -| [Item](./analytics.item.md#item_interface) | Standard Google Analytics Item type. | -| [Promotion](./analytics.promotion.md#promotion_interface) | Field previously used by some Google Analytics events. | -| [SettingsOptions](./analytics.settingsoptions.md#settingsoptions_interface) | Specifies custom options for your Firebase Analytics instance. You must set these before initializing firebase.analytics(). | - -## Type Aliases - -| Type Alias | Description | -| --- | --- | -| [ConsentStatusString](./analytics.md#consentstatusstring) | Whether a particular consent type has been granted or denied. | -| [Currency](./analytics.md#currency) | Standard Google Analytics currency type. | -| [CustomEventName](./analytics.md#customeventname) | Any custom event name string not in the standard list of recommended event names. | -| [EventNameString](./analytics.md#eventnamestring) | Type for standard Google Analytics event names. logEvent also accepts any custom string and interprets it as a custom event name. | - -## getAnalytics() - -Returns an [Analytics](./analytics.analytics.md#analytics_interface) instance for the given app. - -Signature: - -```typescript -export declare function getAnalytics(app?: FirebaseApp): Analytics; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to use. | - -Returns: - -[Analytics](./analytics.analytics.md#analytics_interface) - -## initializeAnalytics() - -Returns an [Analytics](./analytics.analytics.md#analytics_interface) instance for the given app. - -Signature: - -```typescript -export declare function initializeAnalytics(app: FirebaseApp, options?: AnalyticsSettings): Analytics; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to use. | -| options | [AnalyticsSettings](./analytics.analyticssettings.md#analyticssettings_interface) | | - -Returns: - -[Analytics](./analytics.analytics.md#analytics_interface) - -## isSupported() - -This is a public static method provided to users that wraps four different checks: - -1. Check if it's not a browser extension environment. 2. Check if cookies are enabled in current browser. 3. Check if IndexedDB is supported by the browser environment. 4. Check if the current browser context is valid for using `IndexedDB.open()`. - -Signature: - -```typescript -export declare function isSupported(): Promise; -``` -Returns: - -Promise<boolean> - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'add_payment_info', eventParams?: { - coupon?: EventParams['coupon']; - currency?: EventParams['currency']; - items?: EventParams['items']; - payment_type?: EventParams['payment_type']; - value?: EventParams['value']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'add\_payment\_info' | | -| eventParams | { coupon?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['coupon'\]; currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; payment\_type?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['payment\_type'\]; value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'purchase' | 'refund', eventParams?: { - value?: EventParams['value']; - currency?: EventParams['currency']; - transaction_id: EventParams['transaction_id']; - tax?: EventParams['tax']; - shipping?: EventParams['shipping']; - items?: EventParams['items']; - coupon?: EventParams['coupon']; - affiliation?: EventParams['affiliation']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'purchase' \| 'refund' | | -| eventParams | { value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; transaction\_id: [EventParams](./analytics.eventparams.md#eventparams_interface)\['transaction\_id'\]; tax?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['tax'\]; shipping?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['shipping'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; coupon?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['coupon'\]; affiliation?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['affiliation'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -See [Track Screenviews](https://firebase.google.com/docs/analytics/screenviews). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'screen_view', eventParams?: { - firebase_screen: EventParams['firebase_screen']; - firebase_screen_class: EventParams['firebase_screen_class']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'screen\_view' | | -| eventParams | { firebase\_screen: [EventParams](./analytics.eventparams.md#eventparams_interface)\['firebase\_screen'\]; firebase\_screen\_class: [EventParams](./analytics.eventparams.md#eventparams_interface)\['firebase\_screen\_class'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'search' | 'view_search_results', eventParams?: { - search_term?: EventParams['search_term']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'search' \| 'view\_search\_results' | | -| eventParams | { search\_term?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['search\_term'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'select_content', eventParams?: { - content_type?: EventParams['content_type']; - item_id?: EventParams['item_id']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'select\_content' | | -| eventParams | { content\_type?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['content\_type'\]; item\_id?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['item\_id'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'select_item', eventParams?: { - items?: EventParams['items']; - item_list_name?: EventParams['item_list_name']; - item_list_id?: EventParams['item_list_id']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'select\_item' | | -| eventParams | { items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; item\_list\_name?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['item\_list\_name'\]; item\_list\_id?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['item\_list\_id'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'select_promotion' | 'view_promotion', eventParams?: { - items?: EventParams['items']; - promotion_id?: EventParams['promotion_id']; - promotion_name?: EventParams['promotion_name']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'select\_promotion' \| 'view\_promotion' | | -| eventParams | { items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; promotion\_id?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['promotion\_id'\]; promotion\_name?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['promotion\_name'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'set_checkout_option', eventParams?: { - checkout_step?: EventParams['checkout_step']; - checkout_option?: EventParams['checkout_option']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'set\_checkout\_option' | | -| eventParams | { checkout\_step?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['checkout\_step'\]; checkout\_option?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['checkout\_option'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'share', eventParams?: { - method?: EventParams['method']; - content_type?: EventParams['content_type']; - item_id?: EventParams['item_id']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'share' | | -| eventParams | { method?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['method'\]; content\_type?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['content\_type'\]; item\_id?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['item\_id'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'sign_up', eventParams?: { - method?: EventParams['method']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'sign\_up' | | -| eventParams | { method?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['method'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'timing_complete', eventParams?: { - name: string; - value: number; - event_category?: string; - event_label?: string; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'timing\_complete' | | -| eventParams | { name: string; value: number; event\_category?: string; event\_label?: string; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'add_shipping_info', eventParams?: { - coupon?: EventParams['coupon']; - currency?: EventParams['currency']; - items?: EventParams['items']; - shipping_tier?: EventParams['shipping_tier']; - value?: EventParams['value']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'add\_shipping\_info' | | -| eventParams | { coupon?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['coupon'\]; currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; shipping\_tier?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['shipping\_tier'\]; value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'view_cart' | 'view_item', eventParams?: { - currency?: EventParams['currency']; - items?: EventParams['items']; - value?: EventParams['value']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'view\_cart' \| 'view\_item' | | -| eventParams | { currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'view_item_list', eventParams?: { - items?: EventParams['items']; - item_list_name?: EventParams['item_list_name']; - item_list_id?: EventParams['item_list_id']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'view\_item\_list' | | -| eventParams | { items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; item\_list\_name?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['item\_list\_name'\]; item\_list\_id?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['item\_list\_id'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: CustomEventName, eventParams?: { - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | [CustomEventName](./analytics.md#customeventname)<T> | | -| eventParams | { \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'add_to_cart' | 'add_to_wishlist' | 'remove_from_cart', eventParams?: { - currency?: EventParams['currency']; - value?: EventParams['value']; - items?: EventParams['items']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'add\_to\_cart' \| 'add\_to\_wishlist' \| 'remove\_from\_cart' | | -| eventParams | { currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'begin_checkout', eventParams?: { - currency?: EventParams['currency']; - coupon?: EventParams['coupon']; - value?: EventParams['value']; - items?: EventParams['items']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'begin\_checkout' | | -| eventParams | { currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; coupon?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['coupon'\]; value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'checkout_progress', eventParams?: { - currency?: EventParams['currency']; - coupon?: EventParams['coupon']; - value?: EventParams['value']; - items?: EventParams['items']; - checkout_step?: EventParams['checkout_step']; - checkout_option?: EventParams['checkout_option']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'checkout\_progress' | | -| eventParams | { currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; coupon?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['coupon'\]; value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; checkout\_step?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['checkout\_step'\]; checkout\_option?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['checkout\_option'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -See [Measure exceptions](https://developers.google.com/analytics/devguides/collection/ga4/exceptions). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'exception', eventParams?: { - description?: EventParams['description']; - fatal?: EventParams['fatal']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'exception' | | -| eventParams | { description?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['description'\]; fatal?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['fatal'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'generate_lead', eventParams?: { - value?: EventParams['value']; - currency?: EventParams['currency']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'generate\_lead' | | -| eventParams | { value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'login', eventParams?: { - method?: EventParams['method']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'login' | | -| eventParams | { method?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['method'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'page_view', eventParams?: { - page_title?: string; - page_location?: string; - page_path?: string; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'page\_view' | | -| eventParams | { page\_title?: string; page\_location?: string; page\_path?: string; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## setAnalyticsCollectionEnabled() - -Sets whether Google Analytics collection is enabled for this app on this device. Sets global `window['ga-disable-analyticsId'] = true;` - -Signature: - -```typescript -export declare function setAnalyticsCollectionEnabled(analyticsInstance: Analytics, enabled: boolean): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | The [Analytics](./analytics.analytics.md#analytics_interface) instance. | -| enabled | boolean | If true, enables collection, if false, disables it. | - -Returns: - -void - -## setConsent() - -Sets the applicable end user consent state for this web app across all gtag references once Firebase Analytics is initialized. - -Use the [ConsentSettings](./analytics.consentsettings.md#consentsettings_interface) to specify individual consent type values. By default consent types are set to "granted". - -Signature: - -```typescript -export declare function setConsent(consentSettings: ConsentSettings): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| consentSettings | [ConsentSettings](./analytics.consentsettings.md#consentsettings_interface) | Maps the applicable end user consent state for gtag.js. | - -Returns: - -void - -## setCurrentScreen() - -> Warning: This API is now obsolete. -> -> Use with `eventName` as 'screen\_view' and add relevant `eventParams`. See [Track Screenviews](https://firebase.google.com/docs/analytics/screenviews). -> - -Use gtag `config` command to set `screen_name`. - -Signature: - -```typescript -export declare function setCurrentScreen(analyticsInstance: Analytics, screenName: string, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | The [Analytics](./analytics.analytics.md#analytics_interface) instance. | -| screenName | string | Screen name to set. | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## setDefaultEventParameters() - -Adds data that will be set on every event logged from the SDK, including automatic ones. With gtag's "set" command, the values passed persist on the current page and are passed with all subsequent events. - -Signature: - -```typescript -export declare function setDefaultEventParameters(customParams: CustomParams): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| customParams | [CustomParams](./analytics.customparams.md#customparams_interface) | Any custom params the user may pass to gtag.js. | - -Returns: - -void - -## settings() - -Configures Firebase Analytics to use custom `gtag` or `dataLayer` names. Intended to be used if `gtag.js` script has been installed on this page independently of Firebase Analytics, and is using non-default names for either the `gtag` function or for `dataLayer`. Must be called before calling `getAnalytics()` or it won't have any effect. - -Signature: - -```typescript -export declare function settings(options: SettingsOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| options | [SettingsOptions](./analytics.settingsoptions.md#settingsoptions_interface) | Custom gtag and dataLayer names. | - -Returns: - -void - -## setUserId() - -Use gtag `config` command to set `user_id`. - -Signature: - -```typescript -export declare function setUserId(analyticsInstance: Analytics, id: string | null, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | The [Analytics](./analytics.analytics.md#analytics_interface) instance. | -| id | string \| null | User ID to set. | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## setUserProperties() - -Use gtag `config` command to set all params specified. - -Signature: - -```typescript -export declare function setUserProperties(analyticsInstance: Analytics, properties: CustomParams, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| properties | [CustomParams](./analytics.customparams.md#customparams_interface) | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## ConsentStatusString - -Whether a particular consent type has been granted or denied. - -Signature: - -```typescript -export declare type ConsentStatusString = 'granted' | 'denied'; -``` - -## Currency - -Standard Google Analytics currency type. - -Signature: - -```typescript -export declare type Currency = string | number; -``` - -## CustomEventName - -Any custom event name string not in the standard list of recommended event names. - -Signature: - -```typescript -export declare type CustomEventName = T extends EventNameString ? never : T; -``` - -## EventNameString - -Type for standard Google Analytics event names. `logEvent` also accepts any custom string and interprets it as a custom event name. - -Signature: - -```typescript -export declare type EventNameString = 'add_payment_info' | 'add_shipping_info' | 'add_to_cart' | 'add_to_wishlist' | 'begin_checkout' | 'checkout_progress' | 'exception' | 'generate_lead' | 'login' | 'page_view' | 'purchase' | 'refund' | 'remove_from_cart' | 'screen_view' | 'search' | 'select_content' | 'select_item' | 'select_promotion' | 'set_checkout_option' | 'share' | 'sign_up' | 'timing_complete' | 'view_cart' | 'view_item' | 'view_item_list' | 'view_promotion' | 'view_search_results'; -``` diff --git a/docs-devsite/analytics.promotion.md b/docs-devsite/analytics.promotion.md deleted file mode 100644 index 7e29e0335e4..00000000000 --- a/docs-devsite/analytics.promotion.md +++ /dev/null @@ -1,65 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Promotion interface -> Warning: This API is now obsolete. -> -> Use `Item` instead. -> - -Field previously used by some Google Analytics events. - -Signature: - -```typescript -export interface Promotion -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [creative\_name](./analytics.promotion.md#promotioncreative_name) | string | | -| [creative\_slot](./analytics.promotion.md#promotioncreative_slot) | string | | -| [id](./analytics.promotion.md#promotionid) | string | | -| [name](./analytics.promotion.md#promotionname) | string | | - -## Promotion.creative\_name - -Signature: - -```typescript -creative_name?: string; -``` - -## Promotion.creative\_slot - -Signature: - -```typescript -creative_slot?: string; -``` - -## Promotion.id - -Signature: - -```typescript -id?: string; -``` - -## Promotion.name - -Signature: - -```typescript -name?: string; -``` diff --git a/docs-devsite/analytics.settingsoptions.md b/docs-devsite/analytics.settingsoptions.md deleted file mode 100644 index e43152074d0..00000000000 --- a/docs-devsite/analytics.settingsoptions.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# SettingsOptions interface -Specifies custom options for your Firebase Analytics instance. You must set these before initializing `firebase.analytics()`. - -Signature: - -```typescript -export interface SettingsOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [dataLayerName](./analytics.settingsoptions.md#settingsoptionsdatalayername) | string | Sets custom name for dataLayer array used by gtag.js. | -| [gtagName](./analytics.settingsoptions.md#settingsoptionsgtagname) | string | Sets custom name for gtag function. | - -## SettingsOptions.dataLayerName - -Sets custom name for `dataLayer` array used by `gtag.js`. - -Signature: - -```typescript -dataLayerName?: string; -``` - -## SettingsOptions.gtagName - -Sets custom name for `gtag` function. - -Signature: - -```typescript -gtagName?: string; -``` diff --git a/docs-devsite/app-check.appcheck.md b/docs-devsite/app-check.appcheck.md deleted file mode 100644 index a4cb809924d..00000000000 --- a/docs-devsite/app-check.appcheck.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AppCheck interface -The Firebase App Check service interface. - -Signature: - -```typescript -export interface AppCheck -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [app](./app-check.appcheck.md#appcheckapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this AppCheck instance is associated with. | - -## AppCheck.app - -The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `AppCheck` instance is associated with. - -Signature: - -```typescript -app: FirebaseApp; -``` diff --git a/docs-devsite/app-check.appcheckoptions.md b/docs-devsite/app-check.appcheckoptions.md deleted file mode 100644 index 4d3630faa65..00000000000 --- a/docs-devsite/app-check.appcheckoptions.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AppCheckOptions interface -Options for App Check initialization. - -Signature: - -```typescript -export interface AppCheckOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [isTokenAutoRefreshEnabled](./app-check.appcheckoptions.md#appcheckoptionsistokenautorefreshenabled) | boolean | If set to true, enables automatic background refresh of App Check token. | -| [provider](./app-check.appcheckoptions.md#appcheckoptionsprovider) | [CustomProvider](./app-check.customprovider.md#customprovider_class) \| [ReCaptchaV3Provider](./app-check.recaptchav3provider.md#recaptchav3provider_class) \| [ReCaptchaEnterpriseProvider](./app-check.recaptchaenterpriseprovider.md#recaptchaenterpriseprovider_class) | A reCAPTCHA V3 provider, reCAPTCHA Enterprise provider, or custom provider. | - -## AppCheckOptions.isTokenAutoRefreshEnabled - -If set to true, enables automatic background refresh of App Check token. - -Signature: - -```typescript -isTokenAutoRefreshEnabled?: boolean; -``` - -## AppCheckOptions.provider - -A reCAPTCHA V3 provider, reCAPTCHA Enterprise provider, or custom provider. - -Signature: - -```typescript -provider: CustomProvider | ReCaptchaV3Provider | ReCaptchaEnterpriseProvider; -``` diff --git a/docs-devsite/app-check.appchecktoken.md b/docs-devsite/app-check.appchecktoken.md deleted file mode 100644 index 9cb71d78bbb..00000000000 --- a/docs-devsite/app-check.appchecktoken.md +++ /dev/null @@ -1,44 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AppCheckToken interface -The token returned from an App Check provider. - -Signature: - -```typescript -export interface AppCheckToken -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [expireTimeMillis](./app-check.appchecktoken.md#appchecktokenexpiretimemillis) | number | The local timestamp after which the token will expire. | -| [token](./app-check.appchecktoken.md#appchecktokentoken) | string | | - -## AppCheckToken.expireTimeMillis - -The local timestamp after which the token will expire. - -Signature: - -```typescript -readonly expireTimeMillis: number; -``` - -## AppCheckToken.token - -Signature: - -```typescript -readonly token: string; -``` diff --git a/docs-devsite/app-check.appchecktokenresult.md b/docs-devsite/app-check.appchecktokenresult.md deleted file mode 100644 index 185d60992c1..00000000000 --- a/docs-devsite/app-check.appchecktokenresult.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AppCheckTokenResult interface -Result returned by `getToken()`. - -Signature: - -```typescript -export interface AppCheckTokenResult -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [token](./app-check.appchecktokenresult.md#appchecktokenresulttoken) | string | The token string in JWT format. | - -## AppCheckTokenResult.token - -The token string in JWT format. - -Signature: - -```typescript -readonly token: string; -``` diff --git a/docs-devsite/app-check.customprovider.md b/docs-devsite/app-check.customprovider.md deleted file mode 100644 index e00da1d7897..00000000000 --- a/docs-devsite/app-check.customprovider.md +++ /dev/null @@ -1,43 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# CustomProvider class -Custom provider class. - -Signature: - -```typescript -export declare class CustomProvider implements AppCheckProvider -``` -Implements: AppCheckProvider - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(\_customProviderOptions)](./app-check.customprovider.md#customproviderconstructor) | | Constructs a new instance of the CustomProvider class | - -## CustomProvider.(constructor) - -Constructs a new instance of the `CustomProvider` class - -Signature: - -```typescript -constructor(_customProviderOptions: CustomProviderOptions); -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| \_customProviderOptions | [CustomProviderOptions](./app-check.customprovideroptions.md#customprovideroptions_interface) | | - diff --git a/docs-devsite/app-check.customprovideroptions.md b/docs-devsite/app-check.customprovideroptions.md deleted file mode 100644 index c122e0476dd..00000000000 --- a/docs-devsite/app-check.customprovideroptions.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# CustomProviderOptions interface -Options when creating a [CustomProvider](./app-check.customprovider.md#customprovider_class). - -Signature: - -```typescript -export interface CustomProviderOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [getToken](./app-check.customprovideroptions.md#customprovideroptionsgettoken) | () => Promise<[AppCheckToken](./app-check.appchecktoken.md#appchecktoken_interface)> | Function to get an App Check token through a custom provider service. | - -## CustomProviderOptions.getToken - -Function to get an App Check token through a custom provider service. - -Signature: - -```typescript -getToken: () => Promise; -``` diff --git a/docs-devsite/app-check.md b/docs-devsite/app-check.md deleted file mode 100644 index fb1d58fe03b..00000000000 --- a/docs-devsite/app-check.md +++ /dev/null @@ -1,168 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# app-check package -Firebase App Check - -## Functions - -| Function | Description | -| --- | --- | -| [getToken(appCheckInstance, forceRefresh)](./app-check.md#gettoken) | Get the current App Check token. Attaches to the most recent in-flight request if one is present. Returns null if no token is present and no token requests are in-flight. | -| [initializeAppCheck(app, options)](./app-check.md#initializeappcheck) | Activate App Check for the given app. Can be called only once per app. | -| [onTokenChanged(appCheckInstance, observer)](./app-check.md#ontokenchanged) | Registers a listener to changes in the token state. There can be more than one listener registered at the same time for one or more App Check instances. The listeners call back on the UI thread whenever the current token associated with this App Check instance changes. | -| [onTokenChanged(appCheckInstance, onNext, onError, onCompletion)](./app-check.md#ontokenchanged) | Registers a listener to changes in the token state. There can be more than one listener registered at the same time for one or more App Check instances. The listeners call back on the UI thread whenever the current token associated with this App Check instance changes. | -| [setTokenAutoRefreshEnabled(appCheckInstance, isTokenAutoRefreshEnabled)](./app-check.md#settokenautorefreshenabled) | Set whether App Check will automatically refresh tokens as needed. | - -## Classes - -| Class | Description | -| --- | --- | -| [CustomProvider](./app-check.customprovider.md#customprovider_class) | Custom provider class. | -| [ReCaptchaEnterpriseProvider](./app-check.recaptchaenterpriseprovider.md#recaptchaenterpriseprovider_class) | App Check provider that can obtain a reCAPTCHA Enterprise token and exchange it for an App Check token. | -| [ReCaptchaV3Provider](./app-check.recaptchav3provider.md#recaptchav3provider_class) | App Check provider that can obtain a reCAPTCHA V3 token and exchange it for an App Check token. | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [AppCheck](./app-check.appcheck.md#appcheck_interface) | The Firebase App Check service interface. | -| [AppCheckOptions](./app-check.appcheckoptions.md#appcheckoptions_interface) | Options for App Check initialization. | -| [AppCheckToken](./app-check.appchecktoken.md#appchecktoken_interface) | The token returned from an App Check provider. | -| [AppCheckTokenResult](./app-check.appchecktokenresult.md#appchecktokenresult_interface) | Result returned by getToken(). | -| [CustomProviderOptions](./app-check.customprovideroptions.md#customprovideroptions_interface) | Options when creating a [CustomProvider](./app-check.customprovider.md#customprovider_class). | - -## Type Aliases - -| Type Alias | Description | -| --- | --- | -| [AppCheckTokenListener](./app-check.md#appchecktokenlistener) | A listener that is called whenever the App Check token changes. | - -## getToken() - -Get the current App Check token. Attaches to the most recent in-flight request if one is present. Returns null if no token is present and no token requests are in-flight. - -Signature: - -```typescript -export declare function getToken(appCheckInstance: AppCheck, forceRefresh?: boolean): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| appCheckInstance | [AppCheck](./app-check.appcheck.md#appcheck_interface) | The App Check service instance. | -| forceRefresh | boolean | If true, will always try to fetch a fresh token. If false, will use a cached token if found in storage. | - -Returns: - -Promise<[AppCheckTokenResult](./app-check.appchecktokenresult.md#appchecktokenresult_interface)> - -## initializeAppCheck() - -Activate App Check for the given app. Can be called only once per app. - -Signature: - -```typescript -export declare function initializeAppCheck(app: FirebaseApp | undefined, options: AppCheckOptions): AppCheck; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) \| undefined | the [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to activate App Check for | -| options | [AppCheckOptions](./app-check.appcheckoptions.md#appcheckoptions_interface) | App Check initialization options | - -Returns: - -[AppCheck](./app-check.appcheck.md#appcheck_interface) - -## onTokenChanged() - -Registers a listener to changes in the token state. There can be more than one listener registered at the same time for one or more App Check instances. The listeners call back on the UI thread whenever the current token associated with this App Check instance changes. - -Signature: - -```typescript -export declare function onTokenChanged(appCheckInstance: AppCheck, observer: PartialObserver): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| appCheckInstance | [AppCheck](./app-check.appcheck.md#appcheck_interface) | The App Check service instance. | -| observer | [PartialObserver](./util.md#partialobserver)<[AppCheckTokenResult](./app-check.appchecktokenresult.md#appchecktokenresult_interface)> | An object with next, error, and complete properties. next is called with an [AppCheckTokenResult](./app-check.appchecktokenresult.md#appchecktokenresult_interface) whenever the token changes. error is optional and is called if an error is thrown by the listener (the next function). complete is unused, as the token stream is unending. | - -Returns: - -[Unsubscribe](./util.md#unsubscribe) - -A function that unsubscribes this listener. - -## onTokenChanged() - -Registers a listener to changes in the token state. There can be more than one listener registered at the same time for one or more App Check instances. The listeners call back on the UI thread whenever the current token associated with this App Check instance changes. - -Signature: - -```typescript -export declare function onTokenChanged(appCheckInstance: AppCheck, onNext: (tokenResult: AppCheckTokenResult) => void, onError?: (error: Error) => void, onCompletion?: () => void): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| appCheckInstance | [AppCheck](./app-check.appcheck.md#appcheck_interface) | The App Check service instance. | -| onNext | (tokenResult: [AppCheckTokenResult](./app-check.appchecktokenresult.md#appchecktokenresult_interface)) => void | When the token changes, this function is called with aa [AppCheckTokenResult](./app-check.appchecktokenresult.md#appchecktokenresult_interface). | -| onError | (error: Error) => void | Optional. Called if there is an error thrown by the listener (the onNext function). | -| onCompletion | () => void | Currently unused, as the token stream is unending. | - -Returns: - -[Unsubscribe](./util.md#unsubscribe) - -A function that unsubscribes this listener. - -## setTokenAutoRefreshEnabled() - -Set whether App Check will automatically refresh tokens as needed. - -Signature: - -```typescript -export declare function setTokenAutoRefreshEnabled(appCheckInstance: AppCheck, isTokenAutoRefreshEnabled: boolean): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| appCheckInstance | [AppCheck](./app-check.appcheck.md#appcheck_interface) | The App Check service instance. | -| isTokenAutoRefreshEnabled | boolean | If true, the SDK automatically refreshes App Check tokens as needed. This overrides any value set during initializeAppCheck(). | - -Returns: - -void - -## AppCheckTokenListener - -A listener that is called whenever the App Check token changes. - -Signature: - -```typescript -export declare type AppCheckTokenListener = (token: AppCheckTokenResult) => void; -``` diff --git a/docs-devsite/app-check.recaptchaenterpriseprovider.md b/docs-devsite/app-check.recaptchaenterpriseprovider.md deleted file mode 100644 index 21222c24fb9..00000000000 --- a/docs-devsite/app-check.recaptchaenterpriseprovider.md +++ /dev/null @@ -1,43 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ReCaptchaEnterpriseProvider class -App Check provider that can obtain a reCAPTCHA Enterprise token and exchange it for an App Check token. - -Signature: - -```typescript -export declare class ReCaptchaEnterpriseProvider implements AppCheckProvider -``` -Implements: AppCheckProvider - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(\_siteKey)](./app-check.recaptchaenterpriseprovider.md#recaptchaenterpriseproviderconstructor) | | Create a ReCaptchaEnterpriseProvider instance. | - -## ReCaptchaEnterpriseProvider.(constructor) - -Create a ReCaptchaEnterpriseProvider instance. - -Signature: - -```typescript -constructor(_siteKey: string); -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| \_siteKey | string | | - diff --git a/docs-devsite/app-check.recaptchav3provider.md b/docs-devsite/app-check.recaptchav3provider.md deleted file mode 100644 index f2df61a639d..00000000000 --- a/docs-devsite/app-check.recaptchav3provider.md +++ /dev/null @@ -1,43 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ReCaptchaV3Provider class -App Check provider that can obtain a reCAPTCHA V3 token and exchange it for an App Check token. - -Signature: - -```typescript -export declare class ReCaptchaV3Provider implements AppCheckProvider -``` -Implements: AppCheckProvider - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(\_siteKey)](./app-check.recaptchav3provider.md#recaptchav3providerconstructor) | | Create a ReCaptchaV3Provider instance. | - -## ReCaptchaV3Provider.(constructor) - -Create a ReCaptchaV3Provider instance. - -Signature: - -```typescript -constructor(_siteKey: string); -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| \_siteKey | string | | - diff --git a/docs-devsite/app.firebaseapp.md b/docs-devsite/app.firebaseapp.md deleted file mode 100644 index cafbfdd7c54..00000000000 --- a/docs-devsite/app.firebaseapp.md +++ /dev/null @@ -1,91 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FirebaseApp interface -A [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) holds the initialization information for a collection of services. - -Do not call this constructor directly. Instead, use [initializeApp()](./app.md#initializeapp) to create an app. - -Signature: - -```typescript -export interface FirebaseApp -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [automaticDataCollectionEnabled](./app.firebaseapp.md#firebaseappautomaticdatacollectionenabled) | boolean | The settable config flag for GDPR opt-in/opt-out | -| [name](./app.firebaseapp.md#firebaseappname) | string | The (read-only) name for this app.The default app's name is "[DEFAULT]". | -| [options](./app.firebaseapp.md#firebaseappoptions) | [FirebaseOptions](./app.firebaseoptions.md#firebaseoptions_interface) | The (read-only) configuration options for this app. These are the original parameters given in [initializeApp()](./app.md#initializeapp). | - -## FirebaseApp.automaticDataCollectionEnabled - -The settable config flag for GDPR opt-in/opt-out - -Signature: - -```typescript -automaticDataCollectionEnabled: boolean; -``` - -## FirebaseApp.name - -The (read-only) name for this app. - -The default app's name is `"[DEFAULT]"`. - -Signature: - -```typescript -readonly name: string; -``` - -### Example 1 - - -```javascript -// The default app's name is "[DEFAULT]" -const app = initializeApp(defaultAppConfig); -console.log(app.name); // "[DEFAULT]" - -``` - -### Example 2 - - -```javascript -// A named app's name is what you provide to initializeApp() -const otherApp = initializeApp(otherAppConfig, "other"); -console.log(otherApp.name); // "other" - -``` - -## FirebaseApp.options - -The (read-only) configuration options for this app. These are the original parameters given in [initializeApp()](./app.md#initializeapp). - -Signature: - -```typescript -readonly options: FirebaseOptions; -``` - -### Example - - -```javascript -const app = initializeApp(config); -console.log(app.options.databaseURL === config.databaseURL); // true - -``` - diff --git a/docs-devsite/app.firebaseappsettings.md b/docs-devsite/app.firebaseappsettings.md deleted file mode 100644 index 3d9f858e548..00000000000 --- a/docs-devsite/app.firebaseappsettings.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FirebaseAppSettings interface -Configuration options given to [initializeApp()](./app.md#initializeapp) - -Signature: - -```typescript -export interface FirebaseAppSettings -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [automaticDataCollectionEnabled](./app.firebaseappsettings.md#firebaseappsettingsautomaticdatacollectionenabled) | boolean | The settable config flag for GDPR opt-in/opt-out | -| [name](./app.firebaseappsettings.md#firebaseappsettingsname) | string | custom name for the Firebase App. The default value is "[DEFAULT]". | - -## FirebaseAppSettings.automaticDataCollectionEnabled - -The settable config flag for GDPR opt-in/opt-out - -Signature: - -```typescript -automaticDataCollectionEnabled?: boolean; -``` - -## FirebaseAppSettings.name - -custom name for the Firebase App. The default value is `"[DEFAULT]"`. - -Signature: - -```typescript -name?: string; -``` diff --git a/docs-devsite/app.firebaseoptions.md b/docs-devsite/app.firebaseoptions.md deleted file mode 100644 index 5061c901676..00000000000 --- a/docs-devsite/app.firebaseoptions.md +++ /dev/null @@ -1,112 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FirebaseOptions interface -Firebase configuration object. Contains a set of parameters required by services in order to successfully communicate with Firebase server APIs and to associate client data with your Firebase project and Firebase application. Typically this object is populated by the Firebase console at project setup. See also: [Learn about the Firebase config object](https://firebase.google.com/docs/web/setup#config-object). - -Signature: - -```typescript -export interface FirebaseOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [apiKey](./app.firebaseoptions.md#firebaseoptionsapikey) | string | An encrypted string used when calling certain APIs that don't need to access private user data (example value: AIzaSyDOCAbC123dEf456GhI789jKl012-MnO). | -| [appId](./app.firebaseoptions.md#firebaseoptionsappid) | string | Unique identifier for the app. | -| [authDomain](./app.firebaseoptions.md#firebaseoptionsauthdomain) | string | Auth domain for the project ID. | -| [databaseURL](./app.firebaseoptions.md#firebaseoptionsdatabaseurl) | string | Default Realtime Database URL. | -| [measurementId](./app.firebaseoptions.md#firebaseoptionsmeasurementid) | string | An ID automatically created when you enable Analytics in your Firebase project and register a web app. In versions 7.20.0 and higher, this parameter is optional. | -| [messagingSenderId](./app.firebaseoptions.md#firebaseoptionsmessagingsenderid) | string | Unique numerical value used to identify each sender that can send Firebase Cloud Messaging messages to client apps. | -| [projectId](./app.firebaseoptions.md#firebaseoptionsprojectid) | string | The unique identifier for the project across all of Firebase and Google Cloud. | -| [storageBucket](./app.firebaseoptions.md#firebaseoptionsstoragebucket) | string | The default Cloud Storage bucket name. | - -## FirebaseOptions.apiKey - -An encrypted string used when calling certain APIs that don't need to access private user data (example value: `AIzaSyDOCAbC123dEf456GhI789jKl012-MnO`). - -Signature: - -```typescript -apiKey?: string; -``` - -## FirebaseOptions.appId - -Unique identifier for the app. - -Signature: - -```typescript -appId?: string; -``` - -## FirebaseOptions.authDomain - -Auth domain for the project ID. - -Signature: - -```typescript -authDomain?: string; -``` - -## FirebaseOptions.databaseURL - -Default Realtime Database URL. - -Signature: - -```typescript -databaseURL?: string; -``` - -## FirebaseOptions.measurementId - -An ID automatically created when you enable Analytics in your Firebase project and register a web app. In versions 7.20.0 and higher, this parameter is optional. - -Signature: - -```typescript -measurementId?: string; -``` - -## FirebaseOptions.messagingSenderId - -Unique numerical value used to identify each sender that can send Firebase Cloud Messaging messages to client apps. - -Signature: - -```typescript -messagingSenderId?: string; -``` - -## FirebaseOptions.projectId - -The unique identifier for the project across all of Firebase and Google Cloud. - -Signature: - -```typescript -projectId?: string; -``` - -## FirebaseOptions.storageBucket - -The default Cloud Storage bucket name. - -Signature: - -```typescript -storageBucket?: string; -``` diff --git a/docs-devsite/app.md b/docs-devsite/app.md deleted file mode 100644 index d95e7430f71..00000000000 --- a/docs-devsite/app.md +++ /dev/null @@ -1,299 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# app package -Firebase App - -This package coordinates the communication between the different Firebase components - -## Functions - -| Function | Description | -| --- | --- | -| [deleteApp(app)](./app.md#deleteapp) | Renders this app unusable and frees the resources of all associated services. | -| [getApp(name)](./app.md#getapp) | Retrieves a [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance.When called with no arguments, the default app is returned. When an app name is provided, the app corresponding to that name is returned.An exception is thrown if the app being retrieved has not yet been initialized. | -| [getApps()](./app.md#getapps) | A (read-only) array of all initialized apps. | -| [initializeApp(options, name)](./app.md#initializeapp) | Creates and initializes a [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance.See [Add Firebase to your app](https://firebase.google.com/docs/web/setup#add_firebase_to_your_app) and [Initialize multiple projects](https://firebase.google.com/docs/web/setup#multiple-projects) for detailed documentation. | -| [initializeApp(options, config)](./app.md#initializeapp) | Creates and initializes a FirebaseApp instance. | -| [initializeApp()](./app.md#initializeapp) | Creates and initializes a FirebaseApp instance. | -| [onLog(logCallback, options)](./app.md#onlog) | Sets log handler for all Firebase SDKs. | -| [registerVersion(libraryKeyOrName, version, variant)](./app.md#registerversion) | Registers a library's name and version for platform logging purposes. | -| [setLogLevel(logLevel)](./app.md#setloglevel) | Sets log level for all Firebase SDKs.All of the log types above the current log level are captured (i.e. if you set the log level to info, errors are logged, but debug and verbose logs are not). | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | A [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) holds the initialization information for a collection of services.Do not call this constructor directly. Instead, use [initializeApp()](./app.md#initializeapp) to create an app. | -| [FirebaseAppSettings](./app.firebaseappsettings.md#firebaseappsettings_interface) | Configuration options given to [initializeApp()](./app.md#initializeapp) | -| [FirebaseOptions](./app.firebaseoptions.md#firebaseoptions_interface) | Firebase configuration object. Contains a set of parameters required by services in order to successfully communicate with Firebase server APIs and to associate client data with your Firebase project and Firebase application. Typically this object is populated by the Firebase console at project setup. See also: [Learn about the Firebase config object](https://firebase.google.com/docs/web/setup#config-object). | - -## Variables - -| Variable | Description | -| --- | --- | -| [SDK\_VERSION](./app.md#sdk_version) | The current SDK version. | - -## deleteApp() - -Renders this app unusable and frees the resources of all associated services. - -Signature: - -```typescript -export declare function deleteApp(app: FirebaseApp): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | | - -Returns: - -Promise<void> - -### Example - - -```javascript -deleteApp(app) - .then(function() { - console.log("App deleted successfully"); - }) - .catch(function(error) { - console.log("Error deleting app:", error); - }); - -``` - -## getApp() - -Retrieves a [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. - -When called with no arguments, the default app is returned. When an app name is provided, the app corresponding to that name is returned. - -An exception is thrown if the app being retrieved has not yet been initialized. - -Signature: - -```typescript -export declare function getApp(name?: string): FirebaseApp; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| name | string | Optional name of the app to return. If no name is provided, the default is "[DEFAULT]". | - -Returns: - -[FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) - -The app corresponding to the provided app name. If no app name is provided, the default app is returned. - -### Example 1 - - -```javascript -// Return the default app -const app = getApp(); - -``` - -### Example 2 - - -```javascript -// Return a named app -const otherApp = getApp("otherApp"); - -``` - -## getApps() - -A (read-only) array of all initialized apps. - -Signature: - -```typescript -export declare function getApps(): FirebaseApp[]; -``` -Returns: - -[FirebaseApp](./app.firebaseapp.md#firebaseapp_interface)\[\] - -## initializeApp() - -Creates and initializes a [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. - -See [Add Firebase to your app](https://firebase.google.com/docs/web/setup#add_firebase_to_your_app) and [Initialize multiple projects](https://firebase.google.com/docs/web/setup#multiple-projects) for detailed documentation. - -Signature: - -```typescript -export declare function initializeApp(options: FirebaseOptions, name?: string): FirebaseApp; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| options | [FirebaseOptions](./app.firebaseoptions.md#firebaseoptions_interface) | Options to configure the app's services. | -| name | string | Optional name of the app to initialize. If no name is provided, the default is "[DEFAULT]". | - -Returns: - -[FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) - -The initialized app. - -### Example 1 - - -```javascript - -// Initialize default app -// Retrieve your own options values by adding a web app on -// https://console.firebase.google.com -initializeApp({ - apiKey: "AIza....", // Auth / General Use - authDomain: "YOUR_APP.firebaseapp.com", // Auth with popup/redirect - databaseURL: "https://YOUR_APP.firebaseio.com", // Realtime Database - storageBucket: "YOUR_APP.appspot.com", // Storage - messagingSenderId: "123456789" // Cloud Messaging -}); - -``` - -### Example 2 - - -```javascript - -// Initialize another app -const otherApp = initializeApp({ - databaseURL: "https://.firebaseio.com", - storageBucket: ".appspot.com" -}, "otherApp"); - -``` - -## initializeApp() - -Creates and initializes a FirebaseApp instance. - -Signature: - -```typescript -export declare function initializeApp(options: FirebaseOptions, config?: FirebaseAppSettings): FirebaseApp; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| options | [FirebaseOptions](./app.firebaseoptions.md#firebaseoptions_interface) | Options to configure the app's services. | -| config | [FirebaseAppSettings](./app.firebaseappsettings.md#firebaseappsettings_interface) | FirebaseApp Configuration | - -Returns: - -[FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) - -## initializeApp() - -Creates and initializes a FirebaseApp instance. - -Signature: - -```typescript -export declare function initializeApp(): FirebaseApp; -``` -Returns: - -[FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) - -## onLog() - -Sets log handler for all Firebase SDKs. - -Signature: - -```typescript -export declare function onLog(logCallback: LogCallback | null, options?: LogOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| logCallback | LogCallback \| null | An optional custom log handler that executes user code whenever the Firebase SDK makes a logging call. | -| options | LogOptions | | - -Returns: - -void - -## registerVersion() - -Registers a library's name and version for platform logging purposes. - -Signature: - -```typescript -export declare function registerVersion(libraryKeyOrName: string, version: string, variant?: string): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| libraryKeyOrName | string | | -| version | string | Current version of that library. | -| variant | string | Bundle variant, e.g., node, rn, etc. | - -Returns: - -void - -## setLogLevel() - -Sets log level for all Firebase SDKs. - -All of the log types above the current log level are captured (i.e. if you set the log level to `info`, errors are logged, but `debug` and `verbose` logs are not). - -Signature: - -```typescript -export declare function setLogLevel(logLevel: LogLevelString): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| logLevel | LogLevelString | | - -Returns: - -void - -## SDK\_VERSION - -The current SDK version. - -Signature: - -```typescript -SDK_VERSION: string -``` diff --git a/docs-devsite/auth.actioncodeinfo.md b/docs-devsite/auth.actioncodeinfo.md deleted file mode 100644 index 980acf6d967..00000000000 --- a/docs-devsite/auth.actioncodeinfo.md +++ /dev/null @@ -1,58 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ActionCodeInfo interface -A response from [checkActionCode()](./auth.md#checkactioncode). - -Signature: - -```typescript -export interface ActionCodeInfo -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [data](./auth.actioncodeinfo.md#actioncodeinfodata) | { email?: string \| null; multiFactorInfo?: [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) \| null; previousEmail?: string \| null; } | The data associated with the action code. | -| [operation](./auth.actioncodeinfo.md#actioncodeinfooperation) | typeof [ActionCodeOperationMap](./auth.md#actioncodeoperation)\[keyof typeof [ActionCodeOperationMap](./auth.md#actioncodeoperation)\] | The type of operation that generated the action code. | - -## ActionCodeInfo.data - -The data associated with the action code. - -For the [ActionCodeOperation](./auth.md#actioncodeoperation).PASSWORD\_RESET, [ActionCodeOperation](./auth.md#actioncodeoperation).VERIFY\_EMAIL, and [ActionCodeOperation](./auth.md#actioncodeoperation).RECOVER\_EMAIL actions, this object contains an email field with the address the email was sent to. - -For the [ActionCodeOperation](./auth.md#actioncodeoperation).RECOVER\_EMAIL action, which allows a user to undo an email address change, this object also contains a `previousEmail` field with the user account's current email address. After the action completes, the user's email address will revert to the value in the `email` field from the value in `previousEmail` field. - -For the [ActionCodeOperation](./auth.md#actioncodeoperation).VERIFY\_AND\_CHANGE\_EMAIL action, which allows a user to verify the email before updating it, this object contains a `previousEmail` field with the user account's email address before updating. After the action completes, the user's email address will be updated to the value in the `email` field from the value in `previousEmail` field. - -For the [ActionCodeOperation](./auth.md#actioncodeoperation).REVERT\_SECOND\_FACTOR\_ADDITION action, which allows a user to unenroll a newly added second factor, this object contains a `multiFactorInfo` field with the information about the second factor. For phone second factor, the `multiFactorInfo` is a [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) object, which contains the phone number. - -Signature: - -```typescript -data: { - email?: string | null; - multiFactorInfo?: MultiFactorInfo | null; - previousEmail?: string | null; - }; -``` - -## ActionCodeInfo.operation - -The type of operation that generated the action code. - -Signature: - -```typescript -operation: typeof ActionCodeOperationMap[keyof typeof ActionCodeOperationMap]; -``` diff --git a/docs-devsite/auth.actioncodesettings.md b/docs-devsite/auth.actioncodesettings.md deleted file mode 100644 index a12144adaf4..00000000000 --- a/docs-devsite/auth.actioncodesettings.md +++ /dev/null @@ -1,95 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ActionCodeSettings interface -An interface that defines the required continue/state URL with optional Android and iOS bundle identifiers. - -Signature: - -```typescript -export interface ActionCodeSettings -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [android](./auth.actioncodesettings.md#actioncodesettingsandroid) | { installApp?: boolean; minimumVersion?: string; packageName: string; } | Sets the Android package name. | -| [dynamicLinkDomain](./auth.actioncodesettings.md#actioncodesettingsdynamiclinkdomain) | string | When multiple custom dynamic link domains are defined for a project, specify which one to use when the link is to be opened via a specified mobile app (for example, example.page.link). | -| [handleCodeInApp](./auth.actioncodesettings.md#actioncodesettingshandlecodeinapp) | boolean | When set to true, the action code link will be be sent as a Universal Link or Android App Link and will be opened by the app if installed. | -| [iOS](./auth.actioncodesettings.md#actioncodesettingsios) | { bundleId: string; } | Sets the iOS bundle ID. | -| [url](./auth.actioncodesettings.md#actioncodesettingsurl) | string | Sets the link continue/state URL. | - -## ActionCodeSettings.android - -Sets the Android package name. - -This will try to open the link in an android app if it is installed. If `installApp` is passed, it specifies whether to install the Android app if the device supports it and the app is not already installed. If this field is provided without a `packageName`, an error is thrown explaining that the `packageName` must be provided in conjunction with this field. If `minimumVersion` is specified, and an older version of the app is installed, the user is taken to the Play Store to upgrade the app. - -Signature: - -```typescript -android?: { - installApp?: boolean; - minimumVersion?: string; - packageName: string; - }; -``` - -## ActionCodeSettings.dynamicLinkDomain - -When multiple custom dynamic link domains are defined for a project, specify which one to use when the link is to be opened via a specified mobile app (for example, `example.page.link`). - -Signature: - -```typescript -dynamicLinkDomain?: string; -``` - -## ActionCodeSettings.handleCodeInApp - -When set to true, the action code link will be be sent as a Universal Link or Android App Link and will be opened by the app if installed. - -In the false case, the code will be sent to the web widget first and then on continue will redirect to the app if installed. - -Signature: - -```typescript -handleCodeInApp?: boolean; -``` - -## ActionCodeSettings.iOS - -Sets the iOS bundle ID. - -This will try to open the link in an iOS app if it is installed. - -App installation is not supported for iOS. - -Signature: - -```typescript -iOS?: { - bundleId: string; - }; -``` - -## ActionCodeSettings.url - -Sets the link continue/state URL. - -This has different meanings in different contexts: - When the link is handled in the web action widgets, this is the deep link in the `continueUrl` query parameter. - When the link is handled in the app directly, this is the `continueUrl` query parameter in the deep link of the Dynamic Link. - -Signature: - -```typescript -url: string; -``` diff --git a/docs-devsite/auth.actioncodeurl.md b/docs-devsite/auth.actioncodeurl.md deleted file mode 100644 index f59e20d8c15..00000000000 --- a/docs-devsite/auth.actioncodeurl.md +++ /dev/null @@ -1,121 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ActionCodeURL class -A utility class to parse email action URLs such as password reset, email verification, email link sign in, etc. - -The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `ActionCodeURL` class. - -Signature: - -```typescript -export declare class ActionCodeURL -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [apiKey](./auth.actioncodeurl.md#actioncodeurlapikey) | | string | The API key of the email action link. | -| [code](./auth.actioncodeurl.md#actioncodeurlcode) | | string | The action code of the email action link. | -| [continueUrl](./auth.actioncodeurl.md#actioncodeurlcontinueurl) | | string \| null | The continue URL of the email action link. Null if not provided. | -| [languageCode](./auth.actioncodeurl.md#actioncodeurllanguagecode) | | string \| null | The language code of the email action link. Null if not provided. | -| [operation](./auth.actioncodeurl.md#actioncodeurloperation) | | string | The action performed by the email action link. It returns from one of the types from [ActionCodeInfo](./auth.actioncodeinfo.md#actioncodeinfo_interface) | -| [tenantId](./auth.actioncodeurl.md#actioncodeurltenantid) | | string \| null | The tenant ID of the email action link. Null if the email action is from the parent project. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [parseLink(link)](./auth.actioncodeurl.md#actioncodeurlparselink) | static | Parses the email action link string and returns an [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) if the link is valid, otherwise returns null. | - -## ActionCodeURL.apiKey - -The API key of the email action link. - -Signature: - -```typescript -readonly apiKey: string; -``` - -## ActionCodeURL.code - -The action code of the email action link. - -Signature: - -```typescript -readonly code: string; -``` - -## ActionCodeURL.continueUrl - -The continue URL of the email action link. Null if not provided. - -Signature: - -```typescript -readonly continueUrl: string | null; -``` - -## ActionCodeURL.languageCode - -The language code of the email action link. Null if not provided. - -Signature: - -```typescript -readonly languageCode: string | null; -``` - -## ActionCodeURL.operation - -The action performed by the email action link. It returns from one of the types from [ActionCodeInfo](./auth.actioncodeinfo.md#actioncodeinfo_interface) - -Signature: - -```typescript -readonly operation: string; -``` - -## ActionCodeURL.tenantId - -The tenant ID of the email action link. Null if the email action is from the parent project. - -Signature: - -```typescript -readonly tenantId: string | null; -``` - -## ActionCodeURL.parseLink() - -Parses the email action link string and returns an [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) if the link is valid, otherwise returns null. - -Signature: - -```typescript -static parseLink(link: string): ActionCodeURL | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| link | string | The email action link string. | - -Returns: - -[ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) \| null - -The [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) object, or null if the link is invalid. - diff --git a/docs-devsite/auth.additionaluserinfo.md b/docs-devsite/auth.additionaluserinfo.md deleted file mode 100644 index ec6ca5740ac..00000000000 --- a/docs-devsite/auth.additionaluserinfo.md +++ /dev/null @@ -1,68 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AdditionalUserInfo interface -A structure containing additional user information from a federated identity provider. - -Signature: - -```typescript -export interface AdditionalUserInfo -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [isNewUser](./auth.additionaluserinfo.md#additionaluserinfoisnewuser) | boolean | Whether the user is new (created via sign-up) or existing (authenticated using sign-in). | -| [profile](./auth.additionaluserinfo.md#additionaluserinfoprofile) | Record<string, unknown> \| null | Map containing IDP-specific user data. | -| [providerId](./auth.additionaluserinfo.md#additionaluserinfoproviderid) | string \| null | Identifier for the provider used to authenticate this user. | -| [username](./auth.additionaluserinfo.md#additionaluserinfousername) | string \| null | The username if the provider is GitHub or Twitter. | - -## AdditionalUserInfo.isNewUser - -Whether the user is new (created via sign-up) or existing (authenticated using sign-in). - -Signature: - -```typescript -readonly isNewUser: boolean; -``` - -## AdditionalUserInfo.profile - -Map containing IDP-specific user data. - -Signature: - -```typescript -readonly profile: Record | null; -``` - -## AdditionalUserInfo.providerId - -Identifier for the provider used to authenticate this user. - -Signature: - -```typescript -readonly providerId: string | null; -``` - -## AdditionalUserInfo.username - -The username if the provider is GitHub or Twitter. - -Signature: - -```typescript -readonly username?: string | null; -``` diff --git a/docs-devsite/auth.applicationverifier.md b/docs-devsite/auth.applicationverifier.md deleted file mode 100644 index 08e81aa3362..00000000000 --- a/docs-devsite/auth.applicationverifier.md +++ /dev/null @@ -1,59 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ApplicationVerifier interface -A verifier for domain verification and abuse prevention. - -Currently, the only implementation is [RecaptchaVerifier](./auth.recaptchaverifier.md#recaptchaverifier_class). - -Signature: - -```typescript -export interface ApplicationVerifier -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [type](./auth.applicationverifier.md#applicationverifiertype) | string | Identifies the type of application verifier (e.g. "recaptcha"). | - -## Methods - -| Method | Description | -| --- | --- | -| [verify()](./auth.applicationverifier.md#applicationverifierverify) | Executes the verification process. | - -## ApplicationVerifier.type - -Identifies the type of application verifier (e.g. "recaptcha"). - -Signature: - -```typescript -readonly type: string; -``` - -## ApplicationVerifier.verify() - -Executes the verification process. - -Signature: - -```typescript -verify(): Promise; -``` -Returns: - -Promise<string> - -A Promise for a token that can be used to assert the validity of a request. - diff --git a/docs-devsite/auth.auth.md b/docs-devsite/auth.auth.md deleted file mode 100644 index 9bd59ba6c56..00000000000 --- a/docs-devsite/auth.auth.md +++ /dev/null @@ -1,299 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Auth interface -Interface representing Firebase Auth service. - -See [Firebase Authentication](https://firebase.google.com/docs/auth/) for a full guide on how to use the Firebase Auth service. - -Signature: - -```typescript -export interface Auth -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [app](./auth.auth.md#authapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with the Auth service instance. | -| [config](./auth.auth.md#authconfig) | [Config](./auth.config.md#config_interface) | The [Config](./auth.config.md#config_interface) used to initialize this instance. | -| [currentUser](./auth.auth.md#authcurrentuser) | [User](./auth.user.md#user_interface) \| null | The currently signed-in user (or null). | -| [emulatorConfig](./auth.auth.md#authemulatorconfig) | [EmulatorConfig](./auth.emulatorconfig.md#emulatorconfig_interface) \| null | The current emulator configuration (or null). | -| [languageCode](./auth.auth.md#authlanguagecode) | string \| null | The [Auth](./auth.auth.md#auth_interface) instance's language code. | -| [name](./auth.auth.md#authname) | string | The name of the app associated with the Auth service instance. | -| [settings](./auth.auth.md#authsettings) | [AuthSettings](./auth.authsettings.md#authsettings_interface) | The [Auth](./auth.auth.md#auth_interface) instance's settings. | -| [tenantId](./auth.auth.md#authtenantid) | string \| null | The [Auth](./auth.auth.md#auth_interface) instance's tenant ID. | - -## Methods - -| Method | Description | -| --- | --- | -| [beforeAuthStateChanged(callback, onAbort)](./auth.auth.md#authbeforeauthstatechanged) | Adds a blocking callback that runs before an auth state change sets a new user. | -| [onAuthStateChanged(nextOrObserver, error, completed)](./auth.auth.md#authonauthstatechanged) | Adds an observer for changes to the user's sign-in state. | -| [onIdTokenChanged(nextOrObserver, error, completed)](./auth.auth.md#authonidtokenchanged) | Adds an observer for changes to the signed-in user's ID token. | -| [setPersistence(persistence)](./auth.auth.md#authsetpersistence) | Changes the type of persistence on the Auth instance. | -| [signOut()](./auth.auth.md#authsignout) | Signs out the current user. | -| [updateCurrentUser(user)](./auth.auth.md#authupdatecurrentuser) | Asynchronously sets the provided user as [Auth.currentUser](./auth.auth.md#authcurrentuser) on the [Auth](./auth.auth.md#auth_interface) instance. | -| [useDeviceLanguage()](./auth.auth.md#authusedevicelanguage) | Sets the current language to the default device/browser preference. | - -## Auth.app - -The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with the `Auth` service instance. - -Signature: - -```typescript -readonly app: FirebaseApp; -``` - -## Auth.config - -The [Config](./auth.config.md#config_interface) used to initialize this instance. - -Signature: - -```typescript -readonly config: Config; -``` - -## Auth.currentUser - -The currently signed-in user (or null). - -Signature: - -```typescript -readonly currentUser: User | null; -``` - -## Auth.emulatorConfig - -The current emulator configuration (or null). - -Signature: - -```typescript -readonly emulatorConfig: EmulatorConfig | null; -``` - -## Auth.languageCode - -The [Auth](./auth.auth.md#auth_interface) instance's language code. - -This is a readable/writable property. When set to null, the default Firebase Console language setting is applied. The language code will propagate to email action templates (password reset, email verification and email change revocation), SMS templates for phone authentication, reCAPTCHA verifier and OAuth popup/redirect operations provided the specified providers support localization with the language code specified. - -Signature: - -```typescript -languageCode: string | null; -``` - -## Auth.name - -The name of the app associated with the `Auth` service instance. - -Signature: - -```typescript -readonly name: string; -``` - -## Auth.settings - -The [Auth](./auth.auth.md#auth_interface) instance's settings. - -This is used to edit/read configuration related options such as app verification mode for phone authentication. - -Signature: - -```typescript -readonly settings: AuthSettings; -``` - -## Auth.tenantId - -The [Auth](./auth.auth.md#auth_interface) instance's tenant ID. - -This is a readable/writable property. When you set the tenant ID of an [Auth](./auth.auth.md#auth_interface) instance, all future sign-in/sign-up operations will pass this tenant ID and sign in or sign up users to the specified tenant project. When set to null, users are signed in to the parent project. - -Signature: - -```typescript -tenantId: string | null; -``` - -### Example - - -```javascript -// Set the tenant ID on Auth instance. -auth.tenantId = 'TENANT_PROJECT_ID'; - -// All future sign-in request now include tenant ID. -const result = await signInWithEmailAndPassword(auth, email, password); -// result.user.tenantId should be 'TENANT_PROJECT_ID'. - -``` - -## Auth.beforeAuthStateChanged() - -Adds a blocking callback that runs before an auth state change sets a new user. - -Signature: - -```typescript -beforeAuthStateChanged(callback: (user: User | null) => void | Promise, onAbort?: () => void): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| callback | (user: [User](./auth.user.md#user_interface) \| null) => void \| Promise<void> | callback triggered before new user value is set. If this throws, it blocks the user from being set. | -| onAbort | () => void | callback triggered if a later beforeAuthStateChanged() callback throws, allowing you to undo any side effects. | - -Returns: - -[Unsubscribe](./util.md#unsubscribe) - -## Auth.onAuthStateChanged() - -Adds an observer for changes to the user's sign-in state. - -To keep the old behavior, see [Auth.onIdTokenChanged()](./auth.auth.md#authonidtokenchanged). - -Signature: - -```typescript -onAuthStateChanged(nextOrObserver: NextOrObserver, error?: ErrorFn, completed?: CompleteFn): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| nextOrObserver | [NextOrObserver](./auth.md#nextorobserver)<[User](./auth.user.md#user_interface) \| null> | callback triggered on change. | -| error | [ErrorFn](./util.md#errorfn) | Deprecated. This callback is never triggered. Errors on signing in/out can be caught in promises returned from sign-in/sign-out functions. | -| completed | [CompleteFn](./util.md#completefn) | Deprecated. This callback is never triggered. | - -Returns: - -[Unsubscribe](./util.md#unsubscribe) - -## Auth.onIdTokenChanged() - -Adds an observer for changes to the signed-in user's ID token. - -This includes sign-in, sign-out, and token refresh events. - -Signature: - -```typescript -onIdTokenChanged(nextOrObserver: NextOrObserver, error?: ErrorFn, completed?: CompleteFn): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| nextOrObserver | [NextOrObserver](./auth.md#nextorobserver)<[User](./auth.user.md#user_interface) \| null> | callback triggered on change. | -| error | [ErrorFn](./util.md#errorfn) | Deprecated. This callback is never triggered. Errors on signing in/out can be caught in promises returned from sign-in/sign-out functions. | -| completed | [CompleteFn](./util.md#completefn) | Deprecated. This callback is never triggered. | - -Returns: - -[Unsubscribe](./util.md#unsubscribe) - -## Auth.setPersistence() - -Changes the type of persistence on the `Auth` instance. - -This will affect the currently saved Auth session and applies this type of persistence for future sign-in requests, including sign-in with redirect requests. - -This makes it easy for a user signing in to specify whether their session should be remembered or not. It also makes it easier to never persist the Auth state for applications that are shared by other users or have sensitive data. - -Signature: - -```typescript -setPersistence(persistence: Persistence): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| persistence | [Persistence](./auth.persistence.md#persistence_interface) | The [Persistence](./auth.persistence.md#persistence_interface) to use. | - -Returns: - -Promise<void> - -### Example - - -```javascript -auth.setPersistence(browserSessionPersistence); - -``` - -## Auth.signOut() - -Signs out the current user. - -Signature: - -```typescript -signOut(): Promise; -``` -Returns: - -Promise<void> - -## Auth.updateCurrentUser() - -Asynchronously sets the provided user as [Auth.currentUser](./auth.auth.md#authcurrentuser) on the [Auth](./auth.auth.md#auth_interface) instance. - -A new instance copy of the user provided will be made and set as currentUser. - -This will trigger [Auth.onAuthStateChanged()](./auth.auth.md#authonauthstatechanged) and [Auth.onIdTokenChanged()](./auth.auth.md#authonidtokenchanged) listeners like other sign in methods. - -The operation fails with an error if the user to be updated belongs to a different Firebase project. - -Signature: - -```typescript -updateCurrentUser(user: User | null): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) \| null | The new [User](./auth.user.md#user_interface). | - -Returns: - -Promise<void> - -## Auth.useDeviceLanguage() - -Sets the current language to the default device/browser preference. - -Signature: - -```typescript -useDeviceLanguage(): void; -``` -Returns: - -void - diff --git a/docs-devsite/auth.authcredential.md b/docs-devsite/auth.authcredential.md deleted file mode 100644 index fdc6fe392c4..00000000000 --- a/docs-devsite/auth.authcredential.md +++ /dev/null @@ -1,76 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AuthCredential class -Interface that represents the credentials returned by an [AuthProvider](./auth.authprovider.md#authprovider_interface). - -Implementations specify the details about each auth provider's credential requirements. - -The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `AuthCredential` class. - -Signature: - -```typescript -export declare class AuthCredential -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [providerId](./auth.authcredential.md#authcredentialproviderid) | | string | The authentication provider ID for the credential. | -| [signInMethod](./auth.authcredential.md#authcredentialsigninmethod) | | string | The authentication sign in method for the credential. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [toJSON()](./auth.authcredential.md#authcredentialtojson) | | Returns a JSON-serializable representation of this object. | - -## AuthCredential.providerId - -The authentication provider ID for the credential. - -For example, 'facebook.com', or 'google.com'. - -Signature: - -```typescript -readonly providerId: string; -``` - -## AuthCredential.signInMethod - -The authentication sign in method for the credential. - -For example, [SignInMethod](./auth.md#signinmethod).EMAIL\_PASSWORD, or [SignInMethod](./auth.md#signinmethod).EMAIL\_LINK. This corresponds to the sign-in method identifier as returned in [fetchSignInMethodsForEmail()](./auth.md#fetchsigninmethodsforemail). - -Signature: - -```typescript -readonly signInMethod: string; -``` - -## AuthCredential.toJSON() - -Returns a JSON-serializable representation of this object. - -Signature: - -```typescript -toJSON(): object; -``` -Returns: - -object - -a JSON-serializable representation of this object. - diff --git a/docs-devsite/auth.autherror.md b/docs-devsite/auth.autherror.md deleted file mode 100644 index f91b835b5ed..00000000000 --- a/docs-devsite/auth.autherror.md +++ /dev/null @@ -1,41 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AuthError interface -Interface for an `Auth` error. - -Signature: - -```typescript -export interface AuthError extends FirebaseError -``` -Extends: [FirebaseError](./util.firebaseerror.md#firebaseerror_class) - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [customData](./auth.autherror.md#autherrorcustomdata) | { readonly appName: string; readonly email?: string; readonly phoneNumber?: string; readonly tenantId?: string; } | Details about the Firebase Auth error. | - -## AuthError.customData - -Details about the Firebase Auth error. - -Signature: - -```typescript -readonly customData: { - readonly appName: string; - readonly email?: string; - readonly phoneNumber?: string; - readonly tenantId?: string; - }; -``` diff --git a/docs-devsite/auth.autherrormap.md b/docs-devsite/auth.autherrormap.md deleted file mode 100644 index e0316a8ed59..00000000000 --- a/docs-devsite/auth.autherrormap.md +++ /dev/null @@ -1,27 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AuthErrorMap interface -A mapping of error codes to error messages. - -While error messages are useful for debugging (providing verbose textual context around what went wrong), these strings take up a lot of space in the compiled code. When deploying code in production, using [prodErrorMap](./auth.md#proderrormap) will save you roughly 10k compressed/gzipped over [debugErrorMap](./auth.md#debugerrormap). You can select the error map during initialization: - -```javascript -initializeAuth(app, {errorMap: debugErrorMap}) - -``` -When initializing Auth, [prodErrorMap](./auth.md#proderrormap) is default. - -Signature: - -```typescript -export interface AuthErrorMap -``` diff --git a/docs-devsite/auth.authprovider.md b/docs-devsite/auth.authprovider.md deleted file mode 100644 index a9871dad0a8..00000000000 --- a/docs-devsite/auth.authprovider.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AuthProvider interface -Interface that represents an auth provider, used to facilitate creating [AuthCredential](./auth.authcredential.md#authcredential_class). - -Signature: - -```typescript -export interface AuthProvider -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [providerId](./auth.authprovider.md#authproviderproviderid) | string | Provider for which credentials can be constructed. | - -## AuthProvider.providerId - -Provider for which credentials can be constructed. - -Signature: - -```typescript -readonly providerId: string; -``` diff --git a/docs-devsite/auth.authsettings.md b/docs-devsite/auth.authsettings.md deleted file mode 100644 index c54fac47da4..00000000000 --- a/docs-devsite/auth.authsettings.md +++ /dev/null @@ -1,41 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AuthSettings interface -Interface representing an [Auth](./auth.auth.md#auth_interface) instance's settings. - -Currently used for enabling/disabling app verification for phone Auth testing. - -Signature: - -```typescript -export interface AuthSettings -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [appVerificationDisabledForTesting](./auth.authsettings.md#authsettingsappverificationdisabledfortesting) | boolean | When set, this property disables app verification for the purpose of testing phone authentication. For this property to take effect, it needs to be set before rendering a reCAPTCHA app verifier. When this is disabled, a mock reCAPTCHA is rendered instead. This is useful for manual testing during development or for automated integration tests.In order to use this feature, you will need to [whitelist your phone number](https://firebase.google.com/docs/auth/web/phone-auth#test-with-whitelisted-phone-numbers) via the Firebase Console.The default value is false (app verification is enabled). | - -## AuthSettings.appVerificationDisabledForTesting - -When set, this property disables app verification for the purpose of testing phone authentication. For this property to take effect, it needs to be set before rendering a reCAPTCHA app verifier. When this is disabled, a mock reCAPTCHA is rendered instead. This is useful for manual testing during development or for automated integration tests. - -In order to use this feature, you will need to [whitelist your phone number](https://firebase.google.com/docs/auth/web/phone-auth#test-with-whitelisted-phone-numbers) via the Firebase Console. - -The default value is false (app verification is enabled). - -Signature: - -```typescript -appVerificationDisabledForTesting: boolean; -``` diff --git a/docs-devsite/auth.config.md b/docs-devsite/auth.config.md deleted file mode 100644 index c22a3930f87..00000000000 --- a/docs-devsite/auth.config.md +++ /dev/null @@ -1,90 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Config interface -Interface representing the `Auth` config. - -Signature: - -```typescript -export interface Config -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [apiHost](./auth.config.md#configapihost) | string | The host at which the Firebase Auth backend is running. | -| [apiKey](./auth.config.md#configapikey) | string | The API Key used to communicate with the Firebase Auth backend. | -| [apiScheme](./auth.config.md#configapischeme) | string | The scheme used to communicate with the Firebase Auth backend. | -| [authDomain](./auth.config.md#configauthdomain) | string | The domain at which the web widgets are hosted (provided via Firebase Config). | -| [sdkClientVersion](./auth.config.md#configsdkclientversion) | string | The SDK Client Version. | -| [tokenApiHost](./auth.config.md#configtokenapihost) | string | The host at which the Secure Token API is running. | - -## Config.apiHost - -The host at which the Firebase Auth backend is running. - -Signature: - -```typescript -apiHost: string; -``` - -## Config.apiKey - -The API Key used to communicate with the Firebase Auth backend. - -Signature: - -```typescript -apiKey: string; -``` - -## Config.apiScheme - -The scheme used to communicate with the Firebase Auth backend. - -Signature: - -```typescript -apiScheme: string; -``` - -## Config.authDomain - -The domain at which the web widgets are hosted (provided via Firebase Config). - -Signature: - -```typescript -authDomain?: string; -``` - -## Config.sdkClientVersion - -The SDK Client Version. - -Signature: - -```typescript -sdkClientVersion: string; -``` - -## Config.tokenApiHost - -The host at which the Secure Token API is running. - -Signature: - -```typescript -tokenApiHost: string; -``` diff --git a/docs-devsite/auth.confirmationresult.md b/docs-devsite/auth.confirmationresult.md deleted file mode 100644 index 5d6a209b12d..00000000000 --- a/docs-devsite/auth.confirmationresult.md +++ /dev/null @@ -1,74 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ConfirmationResult interface -A result from a phone number sign-in, link, or reauthenticate call. - -Signature: - -```typescript -export interface ConfirmationResult -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [verificationId](./auth.confirmationresult.md#confirmationresultverificationid) | string | The phone number authentication operation's verification ID. | - -## Methods - -| Method | Description | -| --- | --- | -| [confirm(verificationCode)](./auth.confirmationresult.md#confirmationresultconfirm) | Finishes a phone number sign-in, link, or reauthentication. | - -## ConfirmationResult.verificationId - -The phone number authentication operation's verification ID. - -This can be used along with the verification code to initialize a [PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class). - -Signature: - -```typescript -readonly verificationId: string; -``` - -## ConfirmationResult.confirm() - -Finishes a phone number sign-in, link, or reauthentication. - -Signature: - -```typescript -confirm(verificationCode: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| verificationCode | string | The code that was sent to the user's mobile device. | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -### Example - - -```javascript -const confirmationResult = await signInWithPhoneNumber(auth, phoneNumber, applicationVerifier); -// Obtain verificationCode from the user. -const userCredential = await confirmationResult.confirm(verificationCode); - -``` - diff --git a/docs-devsite/auth.dependencies.md b/docs-devsite/auth.dependencies.md deleted file mode 100644 index 3a2d869ccfe..00000000000 --- a/docs-devsite/auth.dependencies.md +++ /dev/null @@ -1,63 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Dependencies interface -The dependencies that can be used to initialize an [Auth](./auth.auth.md#auth_interface) instance. - -The modular SDK enables tree shaking by allowing explicit declarations of dependencies. For example, a web app does not need to include code that enables Cordova redirect sign in. That functionality is therefore split into [browserPopupRedirectResolver](./auth.md#browserpopupredirectresolver) and . The dependencies object is how Auth is configured to reduce bundle sizes. - -There are two ways to initialize an [Auth](./auth.auth.md#auth_interface) instance: [getAuth()](./auth.md#getauth) and [initializeAuth()](./auth.md#initializeauth). `getAuth` initializes everything using platform-specific configurations, while `initializeAuth` takes a `Dependencies` object directly, giving you more control over what is used. - -Signature: - -```typescript -export interface Dependencies -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [errorMap](./auth.dependencies.md#dependencieserrormap) | [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) | Which [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) to use. | -| [persistence](./auth.dependencies.md#dependenciespersistence) | [Persistence](./auth.persistence.md#persistence_interface) \| [Persistence](./auth.persistence.md#persistence_interface)\[\] | Which [Persistence](./auth.persistence.md#persistence_interface) to use. If this is an array, the first Persistence that the device supports is used. The SDK searches for an existing account in order and, if one is found in a secondary Persistence, the account is moved to the primary Persistence.If no persistence is provided, the SDK falls back on [inMemoryPersistence](./auth.md#inmemorypersistence). | -| [popupRedirectResolver](./auth.dependencies.md#dependenciespopupredirectresolver) | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | The [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) to use. This value depends on the platform. Options are [browserPopupRedirectResolver](./auth.md#browserpopupredirectresolver) and . This field is optional if neither [signInWithPopup()](./auth.md#signinwithpopup) or [signInWithRedirect()](./auth.md#signinwithredirect) are being used. | - -## Dependencies.errorMap - -Which [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) to use. - -Signature: - -```typescript -errorMap?: AuthErrorMap; -``` - -## Dependencies.persistence - -Which [Persistence](./auth.persistence.md#persistence_interface) to use. If this is an array, the first `Persistence` that the device supports is used. The SDK searches for an existing account in order and, if one is found in a secondary `Persistence`, the account is moved to the primary `Persistence`. - -If no persistence is provided, the SDK falls back on [inMemoryPersistence](./auth.md#inmemorypersistence). - -Signature: - -```typescript -persistence?: Persistence | Persistence[]; -``` - -## Dependencies.popupRedirectResolver - -The [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) to use. This value depends on the platform. Options are [browserPopupRedirectResolver](./auth.md#browserpopupredirectresolver) and . This field is optional if neither [signInWithPopup()](./auth.md#signinwithpopup) or [signInWithRedirect()](./auth.md#signinwithredirect) are being used. - -Signature: - -```typescript -popupRedirectResolver?: PopupRedirectResolver; -``` diff --git a/docs-devsite/auth.emailauthcredential.md b/docs-devsite/auth.emailauthcredential.md deleted file mode 100644 index 5d322574b02..00000000000 --- a/docs-devsite/auth.emailauthcredential.md +++ /dev/null @@ -1,69 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# EmailAuthCredential class -Interface that represents the credentials returned by [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) for [ProviderId](./auth.md#providerid).PASSWORD - -Covers both [SignInMethod](./auth.md#signinmethod).EMAIL\_PASSWORD and [SignInMethod](./auth.md#signinmethod).EMAIL\_LINK. - -The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `EmailAuthCredential` class. - -Signature: - -```typescript -export declare class EmailAuthCredential extends AuthCredential -``` -Extends: [AuthCredential](./auth.authcredential.md#authcredential_class) - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [fromJSON(json)](./auth.emailauthcredential.md#emailauthcredentialfromjson) | static | Static method to deserialize a JSON representation of an object into an [AuthCredential](./auth.authcredential.md#authcredential_class). | -| [toJSON()](./auth.emailauthcredential.md#emailauthcredentialtojson) | | Returns a JSON-serializable representation of this object. | - -## EmailAuthCredential.fromJSON() - -Static method to deserialize a JSON representation of an object into an [AuthCredential](./auth.authcredential.md#authcredential_class). - -Signature: - -```typescript -static fromJSON(json: object | string): EmailAuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| json | object \| string | Either object or the stringified representation of the object. When string is provided, JSON.parse would be called first. | - -Returns: - -[EmailAuthCredential](./auth.emailauthcredential.md#emailauthcredential_class) \| null - -If the JSON input does not represent an [AuthCredential](./auth.authcredential.md#authcredential_class), null is returned. - -## EmailAuthCredential.toJSON() - -Returns a JSON-serializable representation of this object. - -Signature: - -```typescript -toJSON(): object; -``` -Returns: - -object - -a JSON-serializable representation of this object. - diff --git a/docs-devsite/auth.emailauthprovider.md b/docs-devsite/auth.emailauthprovider.md deleted file mode 100644 index c1834b1b8c4..00000000000 --- a/docs-devsite/auth.emailauthprovider.md +++ /dev/null @@ -1,159 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# EmailAuthProvider class -Provider for generating [EmailAuthCredential](./auth.emailauthcredential.md#emailauthcredential_class). - -Signature: - -```typescript -export declare class EmailAuthProvider implements AuthProvider -``` -Implements: [AuthProvider](./auth.authprovider.md#authprovider_interface) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [EMAIL\_LINK\_SIGN\_IN\_METHOD](./auth.emailauthprovider.md#emailauthprovideremail_link_sign_in_method) | static | 'emailLink' | Always set to [SignInMethod](./auth.md#signinmethod).EMAIL\_LINK. | -| [EMAIL\_PASSWORD\_SIGN\_IN\_METHOD](./auth.emailauthprovider.md#emailauthprovideremail_password_sign_in_method) | static | 'password' | Always set to [SignInMethod](./auth.md#signinmethod).EMAIL\_PASSWORD. | -| [PROVIDER\_ID](./auth.emailauthprovider.md#emailauthproviderprovider_id) | static | 'password' | Always set to [ProviderId](./auth.md#providerid).PASSWORD, even for email link. | -| [providerId](./auth.emailauthprovider.md#emailauthproviderproviderid) | | "password" | Always set to [ProviderId](./auth.md#providerid).PASSWORD, even for email link. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [credential(email, password)](./auth.emailauthprovider.md#emailauthprovidercredential) | static | Initialize an [AuthCredential](./auth.authcredential.md#authcredential_class) using an email and password. | -| [credentialWithLink(email, emailLink)](./auth.emailauthprovider.md#emailauthprovidercredentialwithlink) | static | Initialize an [AuthCredential](./auth.authcredential.md#authcredential_class) using an email and an email link after a sign in with email link operation. | - -## EmailAuthProvider.EMAIL\_LINK\_SIGN\_IN\_METHOD - -Always set to [SignInMethod](./auth.md#signinmethod).EMAIL\_LINK. - -Signature: - -```typescript -static readonly EMAIL_LINK_SIGN_IN_METHOD: 'emailLink'; -``` - -## EmailAuthProvider.EMAIL\_PASSWORD\_SIGN\_IN\_METHOD - -Always set to [SignInMethod](./auth.md#signinmethod).EMAIL\_PASSWORD. - -Signature: - -```typescript -static readonly EMAIL_PASSWORD_SIGN_IN_METHOD: 'password'; -``` - -## EmailAuthProvider.PROVIDER\_ID - -Always set to [ProviderId](./auth.md#providerid).PASSWORD, even for email link. - -Signature: - -```typescript -static readonly PROVIDER_ID: 'password'; -``` - -## EmailAuthProvider.providerId - -Always set to [ProviderId](./auth.md#providerid).PASSWORD, even for email link. - -Signature: - -```typescript -readonly providerId: "password"; -``` - -## EmailAuthProvider.credential() - -Initialize an [AuthCredential](./auth.authcredential.md#authcredential_class) using an email and password. - -Signature: - -```typescript -static credential(email: string, password: string): EmailAuthCredential; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| email | string | Email address. | -| password | string | User account password. | - -Returns: - -[EmailAuthCredential](./auth.emailauthcredential.md#emailauthcredential_class) - -The auth provider credential. - -### Example 1 - - -```javascript -const authCredential = EmailAuthProvider.credential(email, password); -const userCredential = await signInWithCredential(auth, authCredential); - -``` - -### Example 2 - - -```javascript -const userCredential = await signInWithEmailAndPassword(auth, email, password); - -``` - -## EmailAuthProvider.credentialWithLink() - -Initialize an [AuthCredential](./auth.authcredential.md#authcredential_class) using an email and an email link after a sign in with email link operation. - -Signature: - -```typescript -static credentialWithLink(email: string, emailLink: string): EmailAuthCredential; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| email | string | Email address. | -| emailLink | string | Sign-in email link. | - -Returns: - -[EmailAuthCredential](./auth.emailauthcredential.md#emailauthcredential_class) - -- The auth provider credential. - -### Example 1 - - -```javascript -const authCredential = EmailAuthProvider.credentialWithLink(auth, email, emailLink); -const userCredential = await signInWithCredential(auth, authCredential); - -``` - -### Example 2 - - -```javascript -await sendSignInLinkToEmail(auth, email); -// Obtain emailLink from user. -const userCredential = await signInWithEmailLink(auth, email, emailLink); - -``` - diff --git a/docs-devsite/auth.emulatorconfig.md b/docs-devsite/auth.emulatorconfig.md deleted file mode 100644 index 23f052c8dc4..00000000000 --- a/docs-devsite/auth.emulatorconfig.md +++ /dev/null @@ -1,70 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# EmulatorConfig interface -Configuration of Firebase Authentication Emulator. - -Signature: - -```typescript -export interface EmulatorConfig -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [host](./auth.emulatorconfig.md#emulatorconfighost) | string | The hostname of the emulator, which may be a domain ("localhost"), IPv4 address ("127.0.0.1") or quoted IPv6 address ("\[::1\]"). | -| [options](./auth.emulatorconfig.md#emulatorconfigoptions) | { readonly disableWarnings: boolean; } | The emulator-specific options. | -| [port](./auth.emulatorconfig.md#emulatorconfigport) | number \| null | The port of the emulator, or null if port isn't specified (i.e. protocol default). | -| [protocol](./auth.emulatorconfig.md#emulatorconfigprotocol) | string | The protocol used to communicate with the emulator ("http"/"https"). | - -## EmulatorConfig.host - -The hostname of the emulator, which may be a domain ("localhost"), IPv4 address ("127.0.0.1") or quoted IPv6 address ("\[::1\]"). - -Signature: - -```typescript -readonly host: string; -``` - -## EmulatorConfig.options - -The emulator-specific options. - -Signature: - -```typescript -readonly options: { - readonly disableWarnings: boolean; - }; -``` - -## EmulatorConfig.port - -The port of the emulator, or null if port isn't specified (i.e. protocol default). - -Signature: - -```typescript -readonly port: number | null; -``` - -## EmulatorConfig.protocol - -The protocol used to communicate with the emulator ("http"/"https"). - -Signature: - -```typescript -readonly protocol: string; -``` diff --git a/docs-devsite/auth.facebookauthprovider.md b/docs-devsite/auth.facebookauthprovider.md deleted file mode 100644 index 71ac4eea79c..00000000000 --- a/docs-devsite/auth.facebookauthprovider.md +++ /dev/null @@ -1,182 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FacebookAuthProvider class -Provider for generating an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).FACEBOOK. - -Signature: - -```typescript -export declare class FacebookAuthProvider extends BaseOAuthProvider -``` -Extends: BaseOAuthProvider - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)()](./auth.facebookauthprovider.md#facebookauthproviderconstructor) | | Constructs a new instance of the FacebookAuthProvider class | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [FACEBOOK\_SIGN\_IN\_METHOD](./auth.facebookauthprovider.md#facebookauthproviderfacebook_sign_in_method) | static | 'facebook.com' | Always set to [SignInMethod](./auth.md#signinmethod).FACEBOOK. | -| [PROVIDER\_ID](./auth.facebookauthprovider.md#facebookauthproviderprovider_id) | static | 'facebook.com' | Always set to [ProviderId](./auth.md#providerid).FACEBOOK. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [credential(accessToken)](./auth.facebookauthprovider.md#facebookauthprovidercredential) | static | Creates a credential for Facebook. | -| [credentialFromError(error)](./auth.facebookauthprovider.md#facebookauthprovidercredentialfromerror) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. | -| [credentialFromResult(userCredential)](./auth.facebookauthprovider.md#facebookauthprovidercredentialfromresult) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). | - -## FacebookAuthProvider.(constructor) - -Constructs a new instance of the `FacebookAuthProvider` class - -Signature: - -```typescript -constructor(); -``` - -## FacebookAuthProvider.FACEBOOK\_SIGN\_IN\_METHOD - -Always set to [SignInMethod](./auth.md#signinmethod).FACEBOOK. - -Signature: - -```typescript -static readonly FACEBOOK_SIGN_IN_METHOD: 'facebook.com'; -``` - -## FacebookAuthProvider.PROVIDER\_ID - -Always set to [ProviderId](./auth.md#providerid).FACEBOOK. - -Signature: - -```typescript -static readonly PROVIDER_ID: 'facebook.com'; -``` - -## FacebookAuthProvider.credential() - -Creates a credential for Facebook. - -Signature: - -```typescript -static credential(accessToken: string): OAuthCredential; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| accessToken | string | Facebook access token. | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) - -### Example - - -```javascript -// `event` from the Facebook auth.authResponseChange callback. -const credential = FacebookAuthProvider.credential(event.authResponse.accessToken); -const result = await signInWithCredential(credential); - -``` - -## FacebookAuthProvider.credentialFromError() - -Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. - -Signature: - -```typescript -static credentialFromError(error: FirebaseError): OAuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null - -## FacebookAuthProvider.credentialFromResult() - -Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). - -Signature: - -```typescript -static credentialFromResult(userCredential: UserCredential): OAuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null - -### Example 1 - - -```javascript -// Sign in using a redirect. -const provider = new FacebookAuthProvider(); -// Start a sign in process for an unauthenticated user. -provider.addScope('user_birthday'); -await signInWithRedirect(auth, provider); -// This will trigger a full page redirect away from your app - -// After returning from the redirect when your app initializes you can obtain the result -const result = await getRedirectResult(auth); -if (result) { - // This is the signed-in user - const user = result.user; - // This gives you a Facebook Access Token. - const credential = FacebookAuthProvider.credentialFromResult(result); - const token = credential.accessToken; -} - -``` - -### Example 2 - - -```javascript -// Sign in using a popup. -const provider = new FacebookAuthProvider(); -provider.addScope('user_birthday'); -const result = await signInWithPopup(auth, provider); - -// The signed-in user info. -const user = result.user; -// This gives you a Facebook Access Token. -const credential = FacebookAuthProvider.credentialFromResult(result); -const token = credential.accessToken; - -``` - diff --git a/docs-devsite/auth.githubauthprovider.md b/docs-devsite/auth.githubauthprovider.md deleted file mode 100644 index d2e04bc8125..00000000000 --- a/docs-devsite/auth.githubauthprovider.md +++ /dev/null @@ -1,174 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# GithubAuthProvider class -Provider for generating an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).GITHUB. - -GitHub requires an OAuth 2.0 redirect, so you can either handle the redirect directly, or use the [signInWithPopup()](./auth.md#signinwithpopup) handler: - -Signature: - -```typescript -export declare class GithubAuthProvider extends BaseOAuthProvider -``` -Extends: BaseOAuthProvider - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)()](./auth.githubauthprovider.md#githubauthproviderconstructor) | | Constructs a new instance of the GithubAuthProvider class | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [GITHUB\_SIGN\_IN\_METHOD](./auth.githubauthprovider.md#githubauthprovidergithub_sign_in_method) | static | 'github.com' | Always set to [SignInMethod](./auth.md#signinmethod).GITHUB. | -| [PROVIDER\_ID](./auth.githubauthprovider.md#githubauthproviderprovider_id) | static | 'github.com' | Always set to [ProviderId](./auth.md#providerid).GITHUB. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [credential(accessToken)](./auth.githubauthprovider.md#githubauthprovidercredential) | static | Creates a credential for Github. | -| [credentialFromError(error)](./auth.githubauthprovider.md#githubauthprovidercredentialfromerror) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. | -| [credentialFromResult(userCredential)](./auth.githubauthprovider.md#githubauthprovidercredentialfromresult) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). | - -## GithubAuthProvider.(constructor) - -Constructs a new instance of the `GithubAuthProvider` class - -Signature: - -```typescript -constructor(); -``` - -## GithubAuthProvider.GITHUB\_SIGN\_IN\_METHOD - -Always set to [SignInMethod](./auth.md#signinmethod).GITHUB. - -Signature: - -```typescript -static readonly GITHUB_SIGN_IN_METHOD: 'github.com'; -``` - -## GithubAuthProvider.PROVIDER\_ID - -Always set to [ProviderId](./auth.md#providerid).GITHUB. - -Signature: - -```typescript -static readonly PROVIDER_ID: 'github.com'; -``` - -## GithubAuthProvider.credential() - -Creates a credential for Github. - -Signature: - -```typescript -static credential(accessToken: string): OAuthCredential; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| accessToken | string | Github access token. | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) - -## GithubAuthProvider.credentialFromError() - -Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. - -Signature: - -```typescript -static credentialFromError(error: FirebaseError): OAuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null - -## GithubAuthProvider.credentialFromResult() - -Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). - -Signature: - -```typescript -static credentialFromResult(userCredential: UserCredential): OAuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null - -### Example 1 - - -```javascript -// Sign in using a redirect. -const provider = new GithubAuthProvider(); -// Start a sign in process for an unauthenticated user. -provider.addScope('repo'); -await signInWithRedirect(auth, provider); -// This will trigger a full page redirect away from your app - -// After returning from the redirect when your app initializes you can obtain the result -const result = await getRedirectResult(auth); -if (result) { - // This is the signed-in user - const user = result.user; - // This gives you a Github Access Token. - const credential = GithubAuthProvider.credentialFromResult(result); - const token = credential.accessToken; -} - -``` - -### Example 2 - - -```javascript -// Sign in using a popup. -const provider = new GithubAuthProvider(); -provider.addScope('repo'); -const result = await signInWithPopup(auth, provider); - -// The signed-in user info. -const user = result.user; -// This gives you a Github Access Token. -const credential = GithubAuthProvider.credentialFromResult(result); -const token = credential.accessToken; - -``` - diff --git a/docs-devsite/auth.googleauthprovider.md b/docs-devsite/auth.googleauthprovider.md deleted file mode 100644 index 2e14c0ff88e..00000000000 --- a/docs-devsite/auth.googleauthprovider.md +++ /dev/null @@ -1,185 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# GoogleAuthProvider class -Provider for generating an an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).GOOGLE. - -Signature: - -```typescript -export declare class GoogleAuthProvider extends BaseOAuthProvider -``` -Extends: BaseOAuthProvider - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)()](./auth.googleauthprovider.md#googleauthproviderconstructor) | | Constructs a new instance of the GoogleAuthProvider class | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [GOOGLE\_SIGN\_IN\_METHOD](./auth.googleauthprovider.md#googleauthprovidergoogle_sign_in_method) | static | 'google.com' | Always set to [SignInMethod](./auth.md#signinmethod).GOOGLE. | -| [PROVIDER\_ID](./auth.googleauthprovider.md#googleauthproviderprovider_id) | static | 'google.com' | Always set to [ProviderId](./auth.md#providerid).GOOGLE. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [credential(idToken, accessToken)](./auth.googleauthprovider.md#googleauthprovidercredential) | static | Creates a credential for Google. At least one of ID token and access token is required. | -| [credentialFromError(error)](./auth.googleauthprovider.md#googleauthprovidercredentialfromerror) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. | -| [credentialFromResult(userCredential)](./auth.googleauthprovider.md#googleauthprovidercredentialfromresult) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). | - -## GoogleAuthProvider.(constructor) - -Constructs a new instance of the `GoogleAuthProvider` class - -Signature: - -```typescript -constructor(); -``` - -## GoogleAuthProvider.GOOGLE\_SIGN\_IN\_METHOD - -Always set to [SignInMethod](./auth.md#signinmethod).GOOGLE. - -Signature: - -```typescript -static readonly GOOGLE_SIGN_IN_METHOD: 'google.com'; -``` - -## GoogleAuthProvider.PROVIDER\_ID - -Always set to [ProviderId](./auth.md#providerid).GOOGLE. - -Signature: - -```typescript -static readonly PROVIDER_ID: 'google.com'; -``` - -## GoogleAuthProvider.credential() - -Creates a credential for Google. At least one of ID token and access token is required. - -Signature: - -```typescript -static credential(idToken?: string | null, accessToken?: string | null): OAuthCredential; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| idToken | string \| null | Google ID token. | -| accessToken | string \| null | Google access token. | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) - -### Example - - -```javascript -// \`googleUser\` from the onsuccess Google Sign In callback. -const credential = GoogleAuthProvider.credential(googleUser.getAuthResponse().id_token); -const result = await signInWithCredential(credential); - -``` - -## GoogleAuthProvider.credentialFromError() - -Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. - -Signature: - -```typescript -static credentialFromError(error: FirebaseError): OAuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null - -## GoogleAuthProvider.credentialFromResult() - -Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). - -Signature: - -```typescript -static credentialFromResult(userCredential: UserCredential): OAuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null - -### Example 1 - - -```javascript -// Sign in using a redirect. -const provider = new GoogleAuthProvider(); -// Start a sign in process for an unauthenticated user. -provider.addScope('profile'); -provider.addScope('email'); -await signInWithRedirect(auth, provider); -// This will trigger a full page redirect away from your app - -// After returning from the redirect when your app initializes you can obtain the result -const result = await getRedirectResult(auth); -if (result) { - // This is the signed-in user - const user = result.user; - // This gives you a Google Access Token. - const credential = GoogleAuthProvider.credentialFromResult(result); - const token = credential.accessToken; -} - -``` - -### Example 2 - - -```javascript -// Sign in using a popup. -const provider = new GoogleAuthProvider(); -provider.addScope('profile'); -provider.addScope('email'); -const result = await signInWithPopup(auth, provider); - -// The signed-in user info. -const user = result.user; -// This gives you a Google Access Token. -const credential = GoogleAuthProvider.credentialFromResult(result); -const token = credential.accessToken; - -``` - diff --git a/docs-devsite/auth.idtokenresult.md b/docs-devsite/auth.idtokenresult.md deleted file mode 100644 index f000df924d9..00000000000 --- a/docs-devsite/auth.idtokenresult.md +++ /dev/null @@ -1,109 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# IdTokenResult interface -Interface representing ID token result obtained from [User.getIdTokenResult()](./auth.user.md#usergetidtokenresult). - -`IdTokenResult` contains the ID token JWT string and other helper properties for getting different data associated with the token as well as all the decoded payload claims. - -Note that these claims are not to be trusted as they are parsed client side. Only server side verification can guarantee the integrity of the token claims. - -Signature: - -```typescript -export interface IdTokenResult -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [authTime](./auth.idtokenresult.md#idtokenresultauthtime) | string | The authentication time formatted as a UTC string. | -| [claims](./auth.idtokenresult.md#idtokenresultclaims) | [ParsedToken](./auth.parsedtoken.md#parsedtoken_interface) | The entire payload claims of the ID token including the standard reserved claims as well as the custom claims. | -| [expirationTime](./auth.idtokenresult.md#idtokenresultexpirationtime) | string | The ID token expiration time formatted as a UTC string. | -| [issuedAtTime](./auth.idtokenresult.md#idtokenresultissuedattime) | string | The ID token issuance time formatted as a UTC string. | -| [signInProvider](./auth.idtokenresult.md#idtokenresultsigninprovider) | string \| null | The sign-in provider through which the ID token was obtained (anonymous, custom, phone, password, etc). | -| [signInSecondFactor](./auth.idtokenresult.md#idtokenresultsigninsecondfactor) | string \| null | The type of second factor associated with this session, provided the user was multi-factor authenticated (eg. phone, etc). | -| [token](./auth.idtokenresult.md#idtokenresulttoken) | string | The Firebase Auth ID token JWT string. | - -## IdTokenResult.authTime - -The authentication time formatted as a UTC string. - -This is the time the user authenticated (signed in) and not the time the token was refreshed. - -Signature: - -```typescript -authTime: string; -``` - -## IdTokenResult.claims - -The entire payload claims of the ID token including the standard reserved claims as well as the custom claims. - -Signature: - -```typescript -claims: ParsedToken; -``` - -## IdTokenResult.expirationTime - -The ID token expiration time formatted as a UTC string. - -Signature: - -```typescript -expirationTime: string; -``` - -## IdTokenResult.issuedAtTime - -The ID token issuance time formatted as a UTC string. - -Signature: - -```typescript -issuedAtTime: string; -``` - -## IdTokenResult.signInProvider - -The sign-in provider through which the ID token was obtained (anonymous, custom, phone, password, etc). - -Note, this does not map to provider IDs. - -Signature: - -```typescript -signInProvider: string | null; -``` - -## IdTokenResult.signInSecondFactor - -The type of second factor associated with this session, provided the user was multi-factor authenticated (eg. phone, etc). - -Signature: - -```typescript -signInSecondFactor: string | null; -``` - -## IdTokenResult.token - -The Firebase Auth ID token JWT string. - -Signature: - -```typescript -token: string; -``` diff --git a/docs-devsite/auth.md b/docs-devsite/auth.md deleted file mode 100644 index 022fdce5bd5..00000000000 --- a/docs-devsite/auth.md +++ /dev/null @@ -1,1939 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# auth package -Firebase Authentication - -## Functions - -| Function | Description | -| --- | --- | -| [applyActionCode(auth, oobCode)](./auth.md#applyactioncode) | Applies a verification code sent to the user by email or other out-of-band mechanism. | -| [beforeAuthStateChanged(auth, callback, onAbort)](./auth.md#beforeauthstatechanged) | Adds a blocking callback that runs before an auth state change sets a new user. | -| [checkActionCode(auth, oobCode)](./auth.md#checkactioncode) | Checks a verification code sent to the user by email or other out-of-band mechanism. | -| [confirmPasswordReset(auth, oobCode, newPassword)](./auth.md#confirmpasswordreset) | Completes the password reset process, given a confirmation code and new password. | -| [connectAuthEmulator(auth, url, options)](./auth.md#connectauthemulator) | Changes the [Auth](./auth.auth.md#auth_interface) instance to communicate with the Firebase Auth Emulator, instead of production Firebase Auth services. | -| [createUserWithEmailAndPassword(auth, email, password)](./auth.md#createuserwithemailandpassword) | Creates a new user account associated with the specified email address and password. | -| [deleteUser(user)](./auth.md#deleteuser) | Deletes and signs out the user. | -| [fetchSignInMethodsForEmail(auth, email)](./auth.md#fetchsigninmethodsforemail) | Gets the list of possible sign in methods for the given email address. | -| [getAdditionalUserInfo(userCredential)](./auth.md#getadditionaluserinfo) | Extracts provider specific [AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface) for the given credential. | -| [getAuth(app)](./auth.md#getauth) | Returns the Auth instance associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). If no instance exists, initializes an Auth instance with platform-specific default dependencies. | -| [getIdToken(user, forceRefresh)](./auth.md#getidtoken) | Returns a JSON Web Token (JWT) used to identify the user to a Firebase service. | -| [getIdTokenResult(user, forceRefresh)](./auth.md#getidtokenresult) | Returns a deserialized JSON Web Token (JWT) used to identitfy the user to a Firebase service. | -| [getMultiFactorResolver(auth, error)](./auth.md#getmultifactorresolver) | Provides a [MultiFactorResolver](./auth.multifactorresolver.md#multifactorresolver_interface) suitable for completion of a multi-factor flow. | -| [getRedirectResult(auth, resolver)](./auth.md#getredirectresult) | Returns a [UserCredential](./auth.usercredential.md#usercredential_interface) from the redirect-based sign-in flow. | -| [initializeAuth(app, deps)](./auth.md#initializeauth) | Initializes an [Auth](./auth.auth.md#auth_interface) instance with fine-grained control over [Dependencies](./auth.dependencies.md#dependencies_interface). | -| [isSignInWithEmailLink(auth, emailLink)](./auth.md#issigninwithemaillink) | Checks if an incoming link is a sign-in with email link suitable for [signInWithEmailLink()](./auth.md#signinwithemaillink). | -| [linkWithCredential(user, credential)](./auth.md#linkwithcredential) | Links the user account with the given credentials. | -| [linkWithPhoneNumber(user, phoneNumber, appVerifier)](./auth.md#linkwithphonenumber) | Links the user account with the given phone number. | -| [linkWithPopup(user, provider, resolver)](./auth.md#linkwithpopup) | Links the authenticated provider to the user account using a pop-up based OAuth flow. | -| [linkWithRedirect(user, provider, resolver)](./auth.md#linkwithredirect) | Links the [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) to the user account using a full-page redirect flow. | -| [multiFactor(user)](./auth.md#multifactor) | The [MultiFactorUser](./auth.multifactoruser.md#multifactoruser_interface) corresponding to the user. | -| [onAuthStateChanged(auth, nextOrObserver, error, completed)](./auth.md#onauthstatechanged) | Adds an observer for changes to the user's sign-in state. | -| [onIdTokenChanged(auth, nextOrObserver, error, completed)](./auth.md#onidtokenchanged) | Adds an observer for changes to the signed-in user's ID token. | -| [parseActionCodeURL(link)](./auth.md#parseactioncodeurl) | Parses the email action link string and returns an [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) if the link is valid, otherwise returns null. | -| [reauthenticateWithCredential(user, credential)](./auth.md#reauthenticatewithcredential) | Re-authenticates a user using a fresh credential. | -| [reauthenticateWithPhoneNumber(user, phoneNumber, appVerifier)](./auth.md#reauthenticatewithphonenumber) | Re-authenticates a user using a fresh phone credential. | -| [reauthenticateWithPopup(user, provider, resolver)](./auth.md#reauthenticatewithpopup) | Reauthenticates the current user with the specified [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) using a pop-up based OAuth flow. | -| [reauthenticateWithRedirect(user, provider, resolver)](./auth.md#reauthenticatewithredirect) | Reauthenticates the current user with the specified [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) using a full-page redirect flow. | -| [reload(user)](./auth.md#reload) | Reloads user account data, if signed in. | -| [sendEmailVerification(user, actionCodeSettings)](./auth.md#sendemailverification) | Sends a verification email to a user. | -| [sendPasswordResetEmail(auth, email, actionCodeSettings)](./auth.md#sendpasswordresetemail) | Sends a password reset email to the given email address. | -| [sendSignInLinkToEmail(auth, email, actionCodeSettings)](./auth.md#sendsigninlinktoemail) | Sends a sign-in email link to the user with the specified email. | -| [setPersistence(auth, persistence)](./auth.md#setpersistence) | Changes the type of persistence on the [Auth](./auth.auth.md#auth_interface) instance for the currently saved Auth session and applies this type of persistence for future sign-in requests, including sign-in with redirect requests. | -| [signInAnonymously(auth)](./auth.md#signinanonymously) | Asynchronously signs in as an anonymous user. | -| [signInWithCredential(auth, credential)](./auth.md#signinwithcredential) | Asynchronously signs in with the given credentials. | -| [signInWithCustomToken(auth, customToken)](./auth.md#signinwithcustomtoken) | Asynchronously signs in using a custom token. | -| [signInWithEmailAndPassword(auth, email, password)](./auth.md#signinwithemailandpassword) | Asynchronously signs in using an email and password. | -| [signInWithEmailLink(auth, email, emailLink)](./auth.md#signinwithemaillink) | Asynchronously signs in using an email and sign-in email link. | -| [signInWithPhoneNumber(auth, phoneNumber, appVerifier)](./auth.md#signinwithphonenumber) | Asynchronously signs in using a phone number. | -| [signInWithPopup(auth, provider, resolver)](./auth.md#signinwithpopup) | Authenticates a Firebase client using a popup-based OAuth authentication flow. | -| [signInWithRedirect(auth, provider, resolver)](./auth.md#signinwithredirect) | Authenticates a Firebase client using a full-page redirect flow. | -| [signOut(auth)](./auth.md#signout) | Signs out the current user. | -| [unlink(user, providerId)](./auth.md#unlink) | Unlinks a provider from a user account. | -| [updateCurrentUser(auth, user)](./auth.md#updatecurrentuser) | Asynchronously sets the provided user as [Auth.currentUser](./auth.auth.md#authcurrentuser) on the [Auth](./auth.auth.md#auth_interface) instance. | -| [updateEmail(user, newEmail)](./auth.md#updateemail) | Updates the user's email address. | -| [updatePassword(user, newPassword)](./auth.md#updatepassword) | Updates the user's password. | -| [updatePhoneNumber(user, credential)](./auth.md#updatephonenumber) | Updates the user's phone number. | -| [updateProfile(user, { displayName, photoURL: photoUrl })](./auth.md#updateprofile) | Updates a user's profile data. | -| [useDeviceLanguage(auth)](./auth.md#usedevicelanguage) | Sets the current language to the default device/browser preference. | -| [verifyBeforeUpdateEmail(user, newEmail, actionCodeSettings)](./auth.md#verifybeforeupdateemail) | Sends a verification email to a new email address. | -| [verifyPasswordResetCode(auth, code)](./auth.md#verifypasswordresetcode) | Checks a password reset code sent to the user by email or other out-of-band mechanism. | - -## Classes - -| Class | Description | -| --- | --- | -| [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) | A utility class to parse email action URLs such as password reset, email verification, email link sign in, etc. | -| [AuthCredential](./auth.authcredential.md#authcredential_class) | Interface that represents the credentials returned by an [AuthProvider](./auth.authprovider.md#authprovider_interface). | -| [EmailAuthCredential](./auth.emailauthcredential.md#emailauthcredential_class) | Interface that represents the credentials returned by [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) for [ProviderId](./auth.md#providerid).PASSWORD | -| [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) | Provider for generating [EmailAuthCredential](./auth.emailauthcredential.md#emailauthcredential_class). | -| [FacebookAuthProvider](./auth.facebookauthprovider.md#facebookauthprovider_class) | Provider for generating an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).FACEBOOK. | -| [GithubAuthProvider](./auth.githubauthprovider.md#githubauthprovider_class) | Provider for generating an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).GITHUB. | -| [GoogleAuthProvider](./auth.googleauthprovider.md#googleauthprovider_class) | Provider for generating an an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).GOOGLE. | -| [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) | Represents the OAuth credentials returned by an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). | -| [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) | Provider for generating generic [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). | -| [PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class) | Represents the credentials returned by [PhoneAuthProvider](./auth.phoneauthprovider.md#phoneauthprovider_class). | -| [PhoneAuthProvider](./auth.phoneauthprovider.md#phoneauthprovider_class) | Provider for generating an [PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class). | -| [PhoneMultiFactorGenerator](./auth.phonemultifactorgenerator.md#phonemultifactorgenerator_class) | Provider for generating a [PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface). | -| [RecaptchaVerifier](./auth.recaptchaverifier.md#recaptchaverifier_class) | An [reCAPTCHA](https://www.google.com/recaptcha/)-based application verifier. | -| [SAMLAuthProvider](./auth.samlauthprovider.md#samlauthprovider_class) | An [AuthProvider](./auth.authprovider.md#authprovider_interface) for SAML. | -| [TwitterAuthProvider](./auth.twitterauthprovider.md#twitterauthprovider_class) | Provider for generating an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).TWITTER. | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [ActionCodeInfo](./auth.actioncodeinfo.md#actioncodeinfo_interface) | A response from [checkActionCode()](./auth.md#checkactioncode). | -| [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface) | An interface that defines the required continue/state URL with optional Android and iOS bundle identifiers. | -| [AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface) | A structure containing additional user information from a federated identity provider. | -| [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) | A verifier for domain verification and abuse prevention. | -| [Auth](./auth.auth.md#auth_interface) | Interface representing Firebase Auth service. | -| [AuthError](./auth.autherror.md#autherror_interface) | Interface for an Auth error. | -| [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) | A mapping of error codes to error messages. | -| [AuthProvider](./auth.authprovider.md#authprovider_interface) | Interface that represents an auth provider, used to facilitate creating [AuthCredential](./auth.authcredential.md#authcredential_class). | -| [AuthSettings](./auth.authsettings.md#authsettings_interface) | Interface representing an [Auth](./auth.auth.md#auth_interface) instance's settings. | -| [Config](./auth.config.md#config_interface) | Interface representing the Auth config. | -| [ConfirmationResult](./auth.confirmationresult.md#confirmationresult_interface) | A result from a phone number sign-in, link, or reauthenticate call. | -| [Dependencies](./auth.dependencies.md#dependencies_interface) | The dependencies that can be used to initialize an [Auth](./auth.auth.md#auth_interface) instance. | -| [EmulatorConfig](./auth.emulatorconfig.md#emulatorconfig_interface) | Configuration of Firebase Authentication Emulator. | -| [IdTokenResult](./auth.idtokenresult.md#idtokenresult_interface) | Interface representing ID token result obtained from [User.getIdTokenResult()](./auth.user.md#usergetidtokenresult). | -| [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) | The base class for asserting ownership of a second factor. | -| [MultiFactorError](./auth.multifactorerror.md#multifactorerror_interface) | The error thrown when the user needs to provide a second factor to sign in successfully. | -| [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) | A structure containing the information of a second factor entity. | -| [MultiFactorResolver](./auth.multifactorresolver.md#multifactorresolver_interface) | The class used to facilitate recovery from [MultiFactorError](./auth.multifactorerror.md#multifactorerror_interface) when a user needs to provide a second factor to sign in. | -| [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) | An interface defining the multi-factor session object used for enrolling a second factor on a user or helping sign in an enrolled user with a second factor. | -| [MultiFactorUser](./auth.multifactoruser.md#multifactoruser_interface) | An interface that defines the multi-factor related properties and operations pertaining to a [User](./auth.user.md#user_interface). | -| [OAuthCredentialOptions](./auth.oauthcredentialoptions.md#oauthcredentialoptions_interface) | Defines the options for initializing an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). | -| [ParsedToken](./auth.parsedtoken.md#parsedtoken_interface) | Interface representing a parsed ID token. | -| [Persistence](./auth.persistence.md#persistence_interface) | An interface covering the possible persistence mechanism types. | -| [PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface) | The class for asserting ownership of a phone second factor. Provided by [PhoneMultiFactorGenerator.assertion()](./auth.phonemultifactorgenerator.md#phonemultifactorgeneratorassertion). | -| [PhoneMultiFactorEnrollInfoOptions](./auth.phonemultifactorenrollinfooptions.md#phonemultifactorenrollinfooptions_interface) | Options used for enrolling a second factor. | -| [PhoneMultiFactorInfo](./auth.phonemultifactorinfo.md#phonemultifactorinfo_interface) | The subclass of the [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) interface for phone number second factors. The factorId of this second factor is [FactorId](./auth.md#factorid).PHONE. | -| [PhoneMultiFactorSignInInfoOptions](./auth.phonemultifactorsignininfooptions.md#phonemultifactorsignininfooptions_interface) | Options used for signing in with a second factor. | -| [PhoneSingleFactorInfoOptions](./auth.phonesinglefactorinfooptions.md#phonesinglefactorinfooptions_interface) | Options used for single-factor sign-in. | -| [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | A resolver used for handling DOM specific operations like [signInWithPopup()](./auth.md#signinwithpopup) or [signInWithRedirect()](./auth.md#signinwithredirect). | -| [ReactNativeAsyncStorage](./auth.reactnativeasyncstorage.md#reactnativeasyncstorage_interface) | Interface for a supplied AsyncStorage. | -| [RecaptchaParameters](./auth.recaptchaparameters.md#recaptchaparameters_interface) | Interface representing reCAPTCHA parameters.See the \[reCAPTCHA docs\](https://developers.google.com/recaptcha/docs/display\#render\_param) for the list of accepted parameters. All parameters are accepted except for sitekey: Firebase Auth provisions a reCAPTCHA for each project and will configure the site key upon rendering.For an invisible reCAPTCHA, set the size key to invisible. | -| [User](./auth.user.md#user_interface) | A user account. | -| [UserCredential](./auth.usercredential.md#usercredential_interface) | A structure containing a [User](./auth.user.md#user_interface), the [OperationType](./auth.md#operationtype), and the provider ID. | -| [UserInfo](./auth.userinfo.md#userinfo_interface) | User profile information, visible only to the Firebase project's apps. | -| [UserMetadata](./auth.usermetadata.md#usermetadata_interface) | Interface representing a user's metadata. | - -## Variables - -| Variable | Description | -| --- | --- | -| [ActionCodeOperation](./auth.md#actioncodeoperation) | An enumeration of the possible email action types. | -| [AuthErrorCodes](./auth.md#autherrorcodes) | A map of potential Auth error codes, for easier comparison with errors thrown by the SDK. | -| [browserLocalPersistence](./auth.md#browserlocalpersistence) | An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type LOCAL using localStorage for the underlying storage. | -| [browserPopupRedirectResolver](./auth.md#browserpopupredirectresolver) | An implementation of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) suitable for browser based applications. | -| [browserSessionPersistence](./auth.md#browsersessionpersistence) | An implementation of [Persistence](./auth.persistence.md#persistence_interface) of SESSION using sessionStorage for the underlying storage. | -| [debugErrorMap](./auth.md#debugerrormap) | A verbose error map with detailed descriptions for most error codes.See discussion at [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) | -| [FactorId](./auth.md#factorid) | An enum of factors that may be used for multifactor authentication. | -| [indexedDBLocalPersistence](./auth.md#indexeddblocalpersistence) | An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type LOCAL using indexedDB for the underlying storage. | -| [inMemoryPersistence](./auth.md#inmemorypersistence) | An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type 'NONE'. | -| [OperationType](./auth.md#operationtype) | Enumeration of supported operation types. | -| [prodErrorMap](./auth.md#proderrormap) | A minimal error map with all verbose error messages stripped.See discussion at [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) | -| [ProviderId](./auth.md#providerid) | Enumeration of supported providers. | -| [SignInMethod](./auth.md#signinmethod) | Enumeration of supported sign-in methods. | - -## Type Aliases - -| Type Alias | Description | -| --- | --- | -| [CustomParameters](./auth.md#customparameters) | Map of OAuth Custom Parameters. | -| [NextOrObserver](./auth.md#nextorobserver) | Type definition for an event callback. | -| [PhoneInfoOptions](./auth.md#phoneinfooptions) | The information required to verify the ownership of a phone number. | -| [UserProfile](./auth.md#userprofile) | User profile used in [AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface). | - -## applyActionCode() - -Applies a verification code sent to the user by email or other out-of-band mechanism. - -Signature: - -```typescript -export declare function applyActionCode(auth: Auth, oobCode: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| oobCode | string | A verification code sent to the user. | - -Returns: - -Promise<void> - -## beforeAuthStateChanged() - -Adds a blocking callback that runs before an auth state change sets a new user. - -Signature: - -```typescript -export declare function beforeAuthStateChanged(auth: Auth, callback: (user: User | null) => void | Promise, onAbort?: () => void): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| callback | (user: [User](./auth.user.md#user_interface) \| null) => void \| Promise<void> | callback triggered before new user value is set. If this throws, it blocks the user from being set. | -| onAbort | () => void | callback triggered if a later beforeAuthStateChanged() callback throws, allowing you to undo any side effects. | - -Returns: - -[Unsubscribe](./util.md#unsubscribe) - -## checkActionCode() - -Checks a verification code sent to the user by email or other out-of-band mechanism. - -Signature: - -```typescript -export declare function checkActionCode(auth: Auth, oobCode: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| oobCode | string | A verification code sent to the user. | - -Returns: - -Promise<[ActionCodeInfo](./auth.actioncodeinfo.md#actioncodeinfo_interface)> - -metadata about the code. - -## confirmPasswordReset() - -Completes the password reset process, given a confirmation code and new password. - -Signature: - -```typescript -export declare function confirmPasswordReset(auth: Auth, oobCode: string, newPassword: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| oobCode | string | A confirmation code sent to the user. | -| newPassword | string | The new password. | - -Returns: - -Promise<void> - -## connectAuthEmulator() - -Changes the [Auth](./auth.auth.md#auth_interface) instance to communicate with the Firebase Auth Emulator, instead of production Firebase Auth services. - -This must be called synchronously immediately following the first call to [initializeAuth()](./auth.md#initializeauth). Do not use with production credentials as emulator traffic is not encrypted. - -Signature: - -```typescript -export declare function connectAuthEmulator(auth: Auth, url: string, options?: { - disableWarnings: boolean; -}): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| url | string | The URL at which the emulator is running (eg, 'http://localhost:9099'). | -| options | { disableWarnings: boolean; } | Optional. options.disableWarnings defaults to false. Set it to true to disable the warning banner attached to the DOM. | - -Returns: - -void - -### Example - - -```javascript -connectAuthEmulator(auth, 'http://127.0.0.1:9099', { disableWarnings: true }); - -``` - -## createUserWithEmailAndPassword() - -Creates a new user account associated with the specified email address and password. - -On successful creation of the user account, this user will also be signed in to your application. - -User account creation can fail if the account already exists or the password is invalid. - -Note: The email address acts as a unique identifier for the user and enables an email-based password reset. This function will create a new user account and set the initial user password. - -Signature: - -```typescript -export declare function createUserWithEmailAndPassword(auth: Auth, email: string, password: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| email | string | The user's email address. | -| password | string | The user's chosen password. | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -## deleteUser() - -Deletes and signs out the user. - -Important: this is a security-sensitive operation that requires the user to have recently signed in. If this requirement isn't met, ask the user to authenticate again and then call [reauthenticateWithCredential()](./auth.md#reauthenticatewithcredential). - -Signature: - -```typescript -export declare function deleteUser(user: User): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | - -Returns: - -Promise<void> - -## fetchSignInMethodsForEmail() - -Gets the list of possible sign in methods for the given email address. - -This is useful to differentiate methods of sign-in for the same provider, eg. [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) which has 2 methods of sign-in, [SignInMethod](./auth.md#signinmethod).EMAIL\_PASSWORD and [SignInMethod](./auth.md#signinmethod).EMAIL\_LINK. - -Signature: - -```typescript -export declare function fetchSignInMethodsForEmail(auth: Auth, email: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| email | string | The user's email address. | - -Returns: - -Promise<string\[\]> - -## getAdditionalUserInfo() - -Extracts provider specific [AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface) for the given credential. - -Signature: - -```typescript -export declare function getAdditionalUserInfo(userCredential: UserCredential): AdditionalUserInfo | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | - -Returns: - -[AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface) \| null - -## getAuth() - -Returns the Auth instance associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). If no instance exists, initializes an Auth instance with platform-specific default dependencies. - -Signature: - -```typescript -export declare function getAuth(app?: FirebaseApp): Auth; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The Firebase App. | - -Returns: - -[Auth](./auth.auth.md#auth_interface) - -## getIdToken() - -Returns a JSON Web Token (JWT) used to identify the user to a Firebase service. - -Returns the current token if it has not expired or if it will not expire in the next five minutes. Otherwise, this will refresh the token and return a new one. - -Signature: - -```typescript -export declare function getIdToken(user: User, forceRefresh?: boolean): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| forceRefresh | boolean | Force refresh regardless of token expiration. | - -Returns: - -Promise<string> - -## getIdTokenResult() - -Returns a deserialized JSON Web Token (JWT) used to identitfy the user to a Firebase service. - -Returns the current token if it has not expired or if it will not expire in the next five minutes. Otherwise, this will refresh the token and return a new one. - -Signature: - -```typescript -export declare function getIdTokenResult(user: User, forceRefresh?: boolean): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| forceRefresh | boolean | Force refresh regardless of token expiration. | - -Returns: - -Promise<[IdTokenResult](./auth.idtokenresult.md#idtokenresult_interface)> - -## getMultiFactorResolver() - -Provides a [MultiFactorResolver](./auth.multifactorresolver.md#multifactorresolver_interface) suitable for completion of a multi-factor flow. - -Signature: - -```typescript -export declare function getMultiFactorResolver(auth: Auth, error: MultiFactorError): MultiFactorResolver; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| error | [MultiFactorError](./auth.multifactorerror.md#multifactorerror_interface) | The [MultiFactorError](./auth.multifactorerror.md#multifactorerror_interface) raised during a sign-in, or reauthentication operation. | - -Returns: - -[MultiFactorResolver](./auth.multifactorresolver.md#multifactorresolver_interface) - -## getRedirectResult() - -Returns a [UserCredential](./auth.usercredential.md#usercredential_interface) from the redirect-based sign-in flow. - -If sign-in succeeded, returns the signed in user. If sign-in was unsuccessful, fails with an error. If no redirect operation was called, returns `null`. - -Signature: - -```typescript -export declare function getRedirectResult(auth: Auth, resolver?: PopupRedirectResolver): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface) \| null> - -### Example - - -```javascript -// Sign in using a redirect. -const provider = new FacebookAuthProvider(); -// You can add additional scopes to the provider: -provider.addScope('user_birthday'); -// Start a sign in process for an unauthenticated user. -await signInWithRedirect(auth, provider); -// This will trigger a full page redirect away from your app - -// After returning from the redirect when your app initializes you can obtain the result -const result = await getRedirectResult(auth); -if (result) { - // This is the signed-in user - const user = result.user; - // This gives you a Facebook Access Token. - const credential = provider.credentialFromResult(auth, result); - const token = credential.accessToken; -} -// As this API can be used for sign-in, linking and reauthentication, -// check the operationType to determine what triggered this redirect -// operation. -const operationType = result.operationType; - -``` - -## initializeAuth() - -Initializes an [Auth](./auth.auth.md#auth_interface) instance with fine-grained control over [Dependencies](./auth.dependencies.md#dependencies_interface). - -This function allows more control over the [Auth](./auth.auth.md#auth_interface) instance than [getAuth()](./auth.md#getauth). `getAuth` uses platform-specific defaults to supply the [Dependencies](./auth.dependencies.md#dependencies_interface). In general, `getAuth` is the easiest way to initialize Auth and works for most use cases. Use `initializeAuth` if you need control over which persistence layer is used, or to minimize bundle size if you're not using either `signInWithPopup` or `signInWithRedirect`. - -For example, if your app only uses anonymous accounts and you only want accounts saved for the current session, initialize `Auth` with: - -```js -const auth = initializeAuth(app, { - persistence: browserSessionPersistence, - popupRedirectResolver: undefined, -}); - -``` - -Signature: - -```typescript -export declare function initializeAuth(app: FirebaseApp, deps?: Dependencies): Auth; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | | -| deps | [Dependencies](./auth.dependencies.md#dependencies_interface) | | - -Returns: - -[Auth](./auth.auth.md#auth_interface) - -## isSignInWithEmailLink() - -Checks if an incoming link is a sign-in with email link suitable for [signInWithEmailLink()](./auth.md#signinwithemaillink). - -Signature: - -```typescript -export declare function isSignInWithEmailLink(auth: Auth, emailLink: string): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| emailLink | string | The link sent to the user's email address. | - -Returns: - -boolean - -## linkWithCredential() - -Links the user account with the given credentials. - -An [AuthProvider](./auth.authprovider.md#authprovider_interface) can be used to generate the credential. - -Signature: - -```typescript -export declare function linkWithCredential(user: User, credential: AuthCredential): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| credential | [AuthCredential](./auth.authcredential.md#authcredential_class) | The auth credential. | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -## linkWithPhoneNumber() - -Links the user account with the given phone number. - -Signature: - -```typescript -export declare function linkWithPhoneNumber(user: User, phoneNumber: string, appVerifier: ApplicationVerifier): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| phoneNumber | string | The user's phone number in E.164 format (e.g. +16505550101). | -| appVerifier | [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) | The [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface). | - -Returns: - -Promise<[ConfirmationResult](./auth.confirmationresult.md#confirmationresult_interface)> - -## linkWithPopup() - -Links the authenticated provider to the user account using a pop-up based OAuth flow. - -If the linking is successful, the returned result will contain the user and the provider's credential. - -Signature: - -```typescript -export declare function linkWithPopup(user: User, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | -| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -### Example - - -```javascript -// Sign in using some other provider. -const result = await signInWithEmailAndPassword(auth, email, password); -// Link using a popup. -const provider = new FacebookAuthProvider(); -await linkWithPopup(result.user, provider); - -``` - -## linkWithRedirect() - -Links the [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) to the user account using a full-page redirect flow. - -Signature: - -```typescript -export declare function linkWithRedirect(user: User, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | -| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | - -Returns: - -Promise<never> - -### Example - - -```javascript -// Sign in using some other provider. -const result = await signInWithEmailAndPassword(auth, email, password); -// Link using a redirect. -const provider = new FacebookAuthProvider(); -await linkWithRedirect(result.user, provider); -// This will trigger a full page redirect away from your app - -// After returning from the redirect when your app initializes you can obtain the result -const result = await getRedirectResult(auth); - -``` - -## multiFactor() - -The [MultiFactorUser](./auth.multifactoruser.md#multifactoruser_interface) corresponding to the user. - -This is used to access all multi-factor properties and operations related to the user. - -Signature: - -```typescript -export declare function multiFactor(user: User): MultiFactorUser; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | - -Returns: - -[MultiFactorUser](./auth.multifactoruser.md#multifactoruser_interface) - -## onAuthStateChanged() - -Adds an observer for changes to the user's sign-in state. - -To keep the old behavior, see [onIdTokenChanged()](./auth.md#onidtokenchanged). - -Signature: - -```typescript -export declare function onAuthStateChanged(auth: Auth, nextOrObserver: NextOrObserver, error?: ErrorFn, completed?: CompleteFn): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| nextOrObserver | [NextOrObserver](./auth.md#nextorobserver)<[User](./auth.user.md#user_interface)> | callback triggered on change. | -| error | [ErrorFn](./util.md#errorfn) | Deprecated. This callback is never triggered. Errors on signing in/out can be caught in promises returned from sign-in/sign-out functions. | -| completed | [CompleteFn](./util.md#completefn) | Deprecated. This callback is never triggered. | - -Returns: - -[Unsubscribe](./util.md#unsubscribe) - -## onIdTokenChanged() - -Adds an observer for changes to the signed-in user's ID token. - -This includes sign-in, sign-out, and token refresh events. - -Signature: - -```typescript -export declare function onIdTokenChanged(auth: Auth, nextOrObserver: NextOrObserver, error?: ErrorFn, completed?: CompleteFn): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| nextOrObserver | [NextOrObserver](./auth.md#nextorobserver)<[User](./auth.user.md#user_interface)> | callback triggered on change. | -| error | [ErrorFn](./util.md#errorfn) | Deprecated. This callback is never triggered. Errors on signing in/out can be caught in promises returned from sign-in/sign-out functions. | -| completed | [CompleteFn](./util.md#completefn) | Deprecated. This callback is never triggered. | - -Returns: - -[Unsubscribe](./util.md#unsubscribe) - -## parseActionCodeURL() - -Parses the email action link string and returns an [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) if the link is valid, otherwise returns null. - -Signature: - -```typescript -export declare function parseActionCodeURL(link: string): ActionCodeURL | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| link | string | | - -Returns: - -[ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) \| null - -## reauthenticateWithCredential() - -Re-authenticates a user using a fresh credential. - -Use before operations such as [updatePassword()](./auth.md#updatepassword) that require tokens from recent sign-in attempts. This method can be used to recover from a `CREDENTIAL_TOO_OLD_LOGIN_AGAIN` error. - -Signature: - -```typescript -export declare function reauthenticateWithCredential(user: User, credential: AuthCredential): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| credential | [AuthCredential](./auth.authcredential.md#authcredential_class) | The auth credential. | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -## reauthenticateWithPhoneNumber() - -Re-authenticates a user using a fresh phone credential. - -Use before operations such as [updatePassword()](./auth.md#updatepassword) that require tokens from recent sign-in attempts. - -Signature: - -```typescript -export declare function reauthenticateWithPhoneNumber(user: User, phoneNumber: string, appVerifier: ApplicationVerifier): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| phoneNumber | string | The user's phone number in E.164 format (e.g. +16505550101). | -| appVerifier | [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) | The [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface). | - -Returns: - -Promise<[ConfirmationResult](./auth.confirmationresult.md#confirmationresult_interface)> - -## reauthenticateWithPopup() - -Reauthenticates the current user with the specified [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) using a pop-up based OAuth flow. - -If the reauthentication is successful, the returned result will contain the user and the provider's credential. - -Signature: - -```typescript -export declare function reauthenticateWithPopup(user: User, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | -| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -### Example - - -```javascript -// Sign in using a popup. -const provider = new FacebookAuthProvider(); -const result = await signInWithPopup(auth, provider); -// Reauthenticate using a popup. -await reauthenticateWithPopup(result.user, provider); - -``` - -## reauthenticateWithRedirect() - -Reauthenticates the current user with the specified [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) using a full-page redirect flow. - -Signature: - -```typescript -export declare function reauthenticateWithRedirect(user: User, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | -| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | - -Returns: - -Promise<never> - -### Example - - -```javascript -// Sign in using a redirect. -const provider = new FacebookAuthProvider(); -const result = await signInWithRedirect(auth, provider); -// This will trigger a full page redirect away from your app - -// After returning from the redirect when your app initializes you can obtain the result -const result = await getRedirectResult(auth); -// Link using a redirect. -await linkWithRedirect(result.user, provider); -// This will again trigger a full page redirect away from your app - -// After returning from the redirect when your app initializes you can obtain the result -const result = await getRedirectResult(auth); - -``` - -## reload() - -Reloads user account data, if signed in. - -Signature: - -```typescript -export declare function reload(user: User): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | - -Returns: - -Promise<void> - -## sendEmailVerification() - -Sends a verification email to a user. - -The verification process is completed by calling [applyActionCode()](./auth.md#applyactioncode). - -Signature: - -```typescript -export declare function sendEmailVerification(user: User, actionCodeSettings?: ActionCodeSettings | null): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| actionCodeSettings | [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface) \| null | The [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface). | - -Returns: - -Promise<void> - -### Example - - -```javascript -const actionCodeSettings = { - url: 'https://www.example.com/?email=user@example.com', - iOS: { - bundleId: 'com.example.ios' - }, - android: { - packageName: 'com.example.android', - installApp: true, - minimumVersion: '12' - }, - handleCodeInApp: true -}; -await sendEmailVerification(user, actionCodeSettings); -// Obtain code from the user. -await applyActionCode(auth, code); - -``` - -## sendPasswordResetEmail() - -Sends a password reset email to the given email address. - -To complete the password reset, call [confirmPasswordReset()](./auth.md#confirmpasswordreset) with the code supplied in the email sent to the user, along with the new password specified by the user. - -Signature: - -```typescript -export declare function sendPasswordResetEmail(auth: Auth, email: string, actionCodeSettings?: ActionCodeSettings): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| email | string | The user's email address. | -| actionCodeSettings | [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface) | The [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface). | - -Returns: - -Promise<void> - -### Example - - -```javascript -const actionCodeSettings = { - url: 'https://www.example.com/?email=user@example.com', - iOS: { - bundleId: 'com.example.ios' - }, - android: { - packageName: 'com.example.android', - installApp: true, - minimumVersion: '12' - }, - handleCodeInApp: true -}; -await sendPasswordResetEmail(auth, 'user@example.com', actionCodeSettings); -// Obtain code from user. -await confirmPasswordReset('user@example.com', code); - -``` - -## sendSignInLinkToEmail() - -Sends a sign-in email link to the user with the specified email. - -The sign-in operation has to always be completed in the app unlike other out of band email actions (password reset and email verifications). This is because, at the end of the flow, the user is expected to be signed in and their Auth state persisted within the app. - -To complete sign in with the email link, call [signInWithEmailLink()](./auth.md#signinwithemaillink) with the email address and the email link supplied in the email sent to the user. - -Signature: - -```typescript -export declare function sendSignInLinkToEmail(auth: Auth, email: string, actionCodeSettings: ActionCodeSettings): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | | -| email | string | The user's email address. | -| actionCodeSettings | [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface) | The [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface). | - -Returns: - -Promise<void> - -### Example - - -```javascript -const actionCodeSettings = { - url: 'https://www.example.com/?email=user@example.com', - iOS: { - bundleId: 'com.example.ios' - }, - android: { - packageName: 'com.example.android', - installApp: true, - minimumVersion: '12' - }, - handleCodeInApp: true -}; -await sendSignInLinkToEmail(auth, 'user@example.com', actionCodeSettings); -// Obtain emailLink from the user. -if(isSignInWithEmailLink(auth, emailLink)) { - await signInWithEmailLink(auth, 'user@example.com', emailLink); -} - -``` - -## setPersistence() - -Changes the type of persistence on the [Auth](./auth.auth.md#auth_interface) instance for the currently saved `Auth` session and applies this type of persistence for future sign-in requests, including sign-in with redirect requests. - -This makes it easy for a user signing in to specify whether their session should be remembered or not. It also makes it easier to never persist the `Auth` state for applications that are shared by other users or have sensitive data. - -Signature: - -```typescript -export declare function setPersistence(auth: Auth, persistence: Persistence): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| persistence | [Persistence](./auth.persistence.md#persistence_interface) | The [Persistence](./auth.persistence.md#persistence_interface) to use. | - -Returns: - -Promise<void> - -A `Promise` that resolves once the persistence change has completed - -### Example - - -```javascript -setPersistence(auth, browserSessionPersistence); - -``` - -## signInAnonymously() - -Asynchronously signs in as an anonymous user. - -If there is already an anonymous user signed in, that user will be returned; otherwise, a new anonymous user identity will be created and returned. - -Signature: - -```typescript -export declare function signInAnonymously(auth: Auth): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -## signInWithCredential() - -Asynchronously signs in with the given credentials. - -An [AuthProvider](./auth.authprovider.md#authprovider_interface) can be used to generate the credential. - -Signature: - -```typescript -export declare function signInWithCredential(auth: Auth, credential: AuthCredential): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| credential | [AuthCredential](./auth.authcredential.md#authcredential_class) | The auth credential. | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -## signInWithCustomToken() - -Asynchronously signs in using a custom token. - -Custom tokens are used to integrate Firebase Auth with existing auth systems, and must be generated by an auth backend using the [createCustomToken](https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#createcustomtoken) method in the [Admin SDK](https://firebase.google.com/docs/auth/admin) . - -Fails with an error if the token is invalid, expired, or not accepted by the Firebase Auth service. - -Signature: - -```typescript -export declare function signInWithCustomToken(auth: Auth, customToken: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| customToken | string | The custom token to sign in with. | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -## signInWithEmailAndPassword() - -Asynchronously signs in using an email and password. - -Fails with an error if the email address and password do not match. - -Note: The user's password is NOT the password used to access the user's email account. The email address serves as a unique identifier for the user, and the password is used to access the user's account in your Firebase project. See also: [createUserWithEmailAndPassword()](./auth.md#createuserwithemailandpassword). - -Signature: - -```typescript -export declare function signInWithEmailAndPassword(auth: Auth, email: string, password: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| email | string | The users email address. | -| password | string | The users password. | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -## signInWithEmailLink() - -Asynchronously signs in using an email and sign-in email link. - -If no link is passed, the link is inferred from the current URL. - -Fails with an error if the email address is invalid or OTP in email link expires. - -Note: Confirm the link is a sign-in email link before calling this method firebase.auth.Auth.isSignInWithEmailLink. - -Signature: - -```typescript -export declare function signInWithEmailLink(auth: Auth, email: string, emailLink?: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| email | string | The user's email address. | -| emailLink | string | The link sent to the user's email address. | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -### Example - - -```javascript -const actionCodeSettings = { - url: 'https://www.example.com/?email=user@example.com', - iOS: { - bundleId: 'com.example.ios' - }, - android: { - packageName: 'com.example.android', - installApp: true, - minimumVersion: '12' - }, - handleCodeInApp: true -}; -await sendSignInLinkToEmail(auth, 'user@example.com', actionCodeSettings); -// Obtain emailLink from the user. -if(isSignInWithEmailLink(auth, emailLink)) { - await signInWithEmailLink(auth, 'user@example.com', emailLink); -} - -``` - -## signInWithPhoneNumber() - -Asynchronously signs in using a phone number. - -This method sends a code via SMS to the given phone number, and returns a [ConfirmationResult](./auth.confirmationresult.md#confirmationresult_interface). After the user provides the code sent to their phone, call [ConfirmationResult.confirm()](./auth.confirmationresult.md#confirmationresultconfirm) with the code to sign the user in. - -For abuse prevention, this method also requires a [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface). This SDK includes a reCAPTCHA-based implementation, [RecaptchaVerifier](./auth.recaptchaverifier.md#recaptchaverifier_class). This function can work on other platforms that do not support the [RecaptchaVerifier](./auth.recaptchaverifier.md#recaptchaverifier_class) (like React Native), but you need to use a third-party [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) implementation. - -Signature: - -```typescript -export declare function signInWithPhoneNumber(auth: Auth, phoneNumber: string, appVerifier: ApplicationVerifier): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| phoneNumber | string | The user's phone number in E.164 format (e.g. +16505550101). | -| appVerifier | [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) | The [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface). | - -Returns: - -Promise<[ConfirmationResult](./auth.confirmationresult.md#confirmationresult_interface)> - -### Example - - -```javascript -// 'recaptcha-container' is the ID of an element in the DOM. -const applicationVerifier = new firebase.auth.RecaptchaVerifier('recaptcha-container'); -const confirmationResult = await signInWithPhoneNumber(auth, phoneNumber, applicationVerifier); -// Obtain a verificationCode from the user. -const credential = await confirmationResult.confirm(verificationCode); - -``` - -## signInWithPopup() - -Authenticates a Firebase client using a popup-based OAuth authentication flow. - -If succeeds, returns the signed in user along with the provider's credential. If sign in was unsuccessful, returns an error object containing additional information about the error. - -Signature: - -```typescript -export declare function signInWithPopup(auth: Auth, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | -| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -### Example - - -```javascript -// Sign in using a popup. -const provider = new FacebookAuthProvider(); -const result = await signInWithPopup(auth, provider); - -// The signed-in user info. -const user = result.user; -// This gives you a Facebook Access Token. -const credential = provider.credentialFromResult(auth, result); -const token = credential.accessToken; - -``` - -## signInWithRedirect() - -Authenticates a Firebase client using a full-page redirect flow. - -To handle the results and errors for this operation, refer to [getRedirectResult()](./auth.md#getredirectresult). - -Signature: - -```typescript -export declare function signInWithRedirect(auth: Auth, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | -| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | - -Returns: - -Promise<never> - -### Example - - -```javascript -// Sign in using a redirect. -const provider = new FacebookAuthProvider(); -// You can add additional scopes to the provider: -provider.addScope('user_birthday'); -// Start a sign in process for an unauthenticated user. -await signInWithRedirect(auth, provider); -// This will trigger a full page redirect away from your app - -// After returning from the redirect when your app initializes you can obtain the result -const result = await getRedirectResult(auth); -if (result) { - // This is the signed-in user - const user = result.user; - // This gives you a Facebook Access Token. - const credential = provider.credentialFromResult(auth, result); - const token = credential.accessToken; -} -// As this API can be used for sign-in, linking and reauthentication, -// check the operationType to determine what triggered this redirect -// operation. -const operationType = result.operationType; - -``` - -## signOut() - -Signs out the current user. - -Signature: - -```typescript -export declare function signOut(auth: Auth): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | - -Returns: - -Promise<void> - -## unlink() - -Unlinks a provider from a user account. - -Signature: - -```typescript -export declare function unlink(user: User, providerId: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| providerId | string | The provider to unlink. | - -Returns: - -Promise<[User](./auth.user.md#user_interface)> - -## updateCurrentUser() - -Asynchronously sets the provided user as [Auth.currentUser](./auth.auth.md#authcurrentuser) on the [Auth](./auth.auth.md#auth_interface) instance. - -A new instance copy of the user provided will be made and set as currentUser. - -This will trigger [onAuthStateChanged()](./auth.md#onauthstatechanged) and [onIdTokenChanged()](./auth.md#onidtokenchanged) listeners like other sign in methods. - -The operation fails with an error if the user to be updated belongs to a different Firebase project. - -Signature: - -```typescript -export declare function updateCurrentUser(auth: Auth, user: User | null): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| user | [User](./auth.user.md#user_interface) \| null | The new [User](./auth.user.md#user_interface). | - -Returns: - -Promise<void> - -## updateEmail() - -Updates the user's email address. - -An email will be sent to the original email address (if it was set) that allows to revoke the email address change, in order to protect them from account hijacking. - -Important: this is a security sensitive operation that requires the user to have recently signed in. If this requirement isn't met, ask the user to authenticate again and then call [reauthenticateWithCredential()](./auth.md#reauthenticatewithcredential). - -Signature: - -```typescript -export declare function updateEmail(user: User, newEmail: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| newEmail | string | The new email address. | - -Returns: - -Promise<void> - -## updatePassword() - -Updates the user's password. - -Important: this is a security sensitive operation that requires the user to have recently signed in. If this requirement isn't met, ask the user to authenticate again and then call [reauthenticateWithCredential()](./auth.md#reauthenticatewithcredential). - -Signature: - -```typescript -export declare function updatePassword(user: User, newPassword: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| newPassword | string | The new password. | - -Returns: - -Promise<void> - -## updatePhoneNumber() - -Updates the user's phone number. - -Signature: - -```typescript -export declare function updatePhoneNumber(user: User, credential: PhoneAuthCredential): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| credential | [PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class) | A credential authenticating the new phone number. | - -Returns: - -Promise<void> - -### Example - - -``` -// 'recaptcha-container' is the ID of an element in the DOM. -const applicationVerifier = new RecaptchaVerifier('recaptcha-container'); -const provider = new PhoneAuthProvider(auth); -const verificationId = await provider.verifyPhoneNumber('+16505550101', applicationVerifier); -// Obtain the verificationCode from the user. -const phoneCredential = PhoneAuthProvider.credential(verificationId, verificationCode); -await updatePhoneNumber(user, phoneCredential); - -``` - -## updateProfile() - -Updates a user's profile data. - -Signature: - -```typescript -export declare function updateProfile(user: User, { displayName, photoURL: photoUrl }: { - displayName?: string | null; - photoURL?: string | null; -}): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| { displayName, photoURL: photoUrl } | { displayName?: string \| null; photoURL?: string \| null; } | | - -Returns: - -Promise<void> - -## useDeviceLanguage() - -Sets the current language to the default device/browser preference. - -Signature: - -```typescript -export declare function useDeviceLanguage(auth: Auth): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | - -Returns: - -void - -## verifyBeforeUpdateEmail() - -Sends a verification email to a new email address. - -The user's email will be updated to the new one after being verified. - -If you have a custom email action handler, you can complete the verification process by calling [applyActionCode()](./auth.md#applyactioncode). - -Signature: - -```typescript -export declare function verifyBeforeUpdateEmail(user: User, newEmail: string, actionCodeSettings?: ActionCodeSettings | null): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| newEmail | string | The new email address to be verified before update. | -| actionCodeSettings | [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface) \| null | The [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface). | - -Returns: - -Promise<void> - -### Example - - -```javascript -const actionCodeSettings = { - url: 'https://www.example.com/?email=user@example.com', - iOS: { - bundleId: 'com.example.ios' - }, - android: { - packageName: 'com.example.android', - installApp: true, - minimumVersion: '12' - }, - handleCodeInApp: true -}; -await verifyBeforeUpdateEmail(user, 'newemail@example.com', actionCodeSettings); -// Obtain code from the user. -await applyActionCode(auth, code); - -``` - -## verifyPasswordResetCode() - -Checks a password reset code sent to the user by email or other out-of-band mechanism. - -Signature: - -```typescript -export declare function verifyPasswordResetCode(auth: Auth, code: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| code | string | A verification code sent to the user. | - -Returns: - -Promise<string> - -the user's email address if valid. - -## ActionCodeOperation - -An enumeration of the possible email action types. - -Signature: - -```typescript -ActionCodeOperation: { - readonly EMAIL_SIGNIN: "EMAIL_SIGNIN"; - readonly PASSWORD_RESET: "PASSWORD_RESET"; - readonly RECOVER_EMAIL: "RECOVER_EMAIL"; - readonly REVERT_SECOND_FACTOR_ADDITION: "REVERT_SECOND_FACTOR_ADDITION"; - readonly VERIFY_AND_CHANGE_EMAIL: "VERIFY_AND_CHANGE_EMAIL"; - readonly VERIFY_EMAIL: "VERIFY_EMAIL"; -} -``` - -## AuthErrorCodes - -A map of potential `Auth` error codes, for easier comparison with errors thrown by the SDK. - -Note that you can't tree-shake individual keys in the map, so by using the map you might substantially increase your bundle size. - -Signature: - -```typescript -AUTH_ERROR_CODES_MAP_DO_NOT_USE_INTERNALLY: { - readonly ADMIN_ONLY_OPERATION: "auth/admin-restricted-operation"; - readonly ARGUMENT_ERROR: "auth/argument-error"; - readonly APP_NOT_AUTHORIZED: "auth/app-not-authorized"; - readonly APP_NOT_INSTALLED: "auth/app-not-installed"; - readonly CAPTCHA_CHECK_FAILED: "auth/captcha-check-failed"; - readonly CODE_EXPIRED: "auth/code-expired"; - readonly CORDOVA_NOT_READY: "auth/cordova-not-ready"; - readonly CORS_UNSUPPORTED: "auth/cors-unsupported"; - readonly CREDENTIAL_ALREADY_IN_USE: "auth/credential-already-in-use"; - readonly CREDENTIAL_MISMATCH: "auth/custom-token-mismatch"; - readonly CREDENTIAL_TOO_OLD_LOGIN_AGAIN: "auth/requires-recent-login"; - readonly DEPENDENT_SDK_INIT_BEFORE_AUTH: "auth/dependent-sdk-initialized-before-auth"; - readonly DYNAMIC_LINK_NOT_ACTIVATED: "auth/dynamic-link-not-activated"; - readonly EMAIL_CHANGE_NEEDS_VERIFICATION: "auth/email-change-needs-verification"; - readonly EMAIL_EXISTS: "auth/email-already-in-use"; - readonly EMULATOR_CONFIG_FAILED: "auth/emulator-config-failed"; - readonly EXPIRED_OOB_CODE: "auth/expired-action-code"; - readonly EXPIRED_POPUP_REQUEST: "auth/cancelled-popup-request"; - readonly INTERNAL_ERROR: "auth/internal-error"; - readonly INVALID_API_KEY: "auth/invalid-api-key"; - readonly INVALID_APP_CREDENTIAL: "auth/invalid-app-credential"; - readonly INVALID_APP_ID: "auth/invalid-app-id"; - readonly INVALID_AUTH: "auth/invalid-user-token"; - readonly INVALID_AUTH_EVENT: "auth/invalid-auth-event"; - readonly INVALID_CERT_HASH: "auth/invalid-cert-hash"; - readonly INVALID_CODE: "auth/invalid-verification-code"; - readonly INVALID_CONTINUE_URI: "auth/invalid-continue-uri"; - readonly INVALID_CORDOVA_CONFIGURATION: "auth/invalid-cordova-configuration"; - readonly INVALID_CUSTOM_TOKEN: "auth/invalid-custom-token"; - readonly INVALID_DYNAMIC_LINK_DOMAIN: "auth/invalid-dynamic-link-domain"; - readonly INVALID_EMAIL: "auth/invalid-email"; - readonly INVALID_EMULATOR_SCHEME: "auth/invalid-emulator-scheme"; - readonly INVALID_IDP_RESPONSE: "auth/invalid-credential"; - readonly INVALID_MESSAGE_PAYLOAD: "auth/invalid-message-payload"; - readonly INVALID_MFA_SESSION: "auth/invalid-multi-factor-session"; - readonly INVALID_OAUTH_CLIENT_ID: "auth/invalid-oauth-client-id"; - readonly INVALID_OAUTH_PROVIDER: "auth/invalid-oauth-provider"; - readonly INVALID_OOB_CODE: "auth/invalid-action-code"; - readonly INVALID_ORIGIN: "auth/unauthorized-domain"; - readonly INVALID_PASSWORD: "auth/wrong-password"; - readonly INVALID_PERSISTENCE: "auth/invalid-persistence-type"; - readonly INVALID_PHONE_NUMBER: "auth/invalid-phone-number"; - readonly INVALID_PROVIDER_ID: "auth/invalid-provider-id"; - readonly INVALID_RECIPIENT_EMAIL: "auth/invalid-recipient-email"; - readonly INVALID_SENDER: "auth/invalid-sender"; - readonly INVALID_SESSION_INFO: "auth/invalid-verification-id"; - readonly INVALID_TENANT_ID: "auth/invalid-tenant-id"; - readonly MFA_INFO_NOT_FOUND: "auth/multi-factor-info-not-found"; - readonly MFA_REQUIRED: "auth/multi-factor-auth-required"; - readonly MISSING_ANDROID_PACKAGE_NAME: "auth/missing-android-pkg-name"; - readonly MISSING_APP_CREDENTIAL: "auth/missing-app-credential"; - readonly MISSING_AUTH_DOMAIN: "auth/auth-domain-config-required"; - readonly MISSING_CODE: "auth/missing-verification-code"; - readonly MISSING_CONTINUE_URI: "auth/missing-continue-uri"; - readonly MISSING_IFRAME_START: "auth/missing-iframe-start"; - readonly MISSING_IOS_BUNDLE_ID: "auth/missing-ios-bundle-id"; - readonly MISSING_OR_INVALID_NONCE: "auth/missing-or-invalid-nonce"; - readonly MISSING_MFA_INFO: "auth/missing-multi-factor-info"; - readonly MISSING_MFA_SESSION: "auth/missing-multi-factor-session"; - readonly MISSING_PHONE_NUMBER: "auth/missing-phone-number"; - readonly MISSING_SESSION_INFO: "auth/missing-verification-id"; - readonly MODULE_DESTROYED: "auth/app-deleted"; - readonly NEED_CONFIRMATION: "auth/account-exists-with-different-credential"; - readonly NETWORK_REQUEST_FAILED: "auth/network-request-failed"; - readonly NULL_USER: "auth/null-user"; - readonly NO_AUTH_EVENT: "auth/no-auth-event"; - readonly NO_SUCH_PROVIDER: "auth/no-such-provider"; - readonly OPERATION_NOT_ALLOWED: "auth/operation-not-allowed"; - readonly OPERATION_NOT_SUPPORTED: "auth/operation-not-supported-in-this-environment"; - readonly POPUP_BLOCKED: "auth/popup-blocked"; - readonly POPUP_CLOSED_BY_USER: "auth/popup-closed-by-user"; - readonly PROVIDER_ALREADY_LINKED: "auth/provider-already-linked"; - readonly QUOTA_EXCEEDED: "auth/quota-exceeded"; - readonly REDIRECT_CANCELLED_BY_USER: "auth/redirect-cancelled-by-user"; - readonly REDIRECT_OPERATION_PENDING: "auth/redirect-operation-pending"; - readonly REJECTED_CREDENTIAL: "auth/rejected-credential"; - readonly SECOND_FACTOR_ALREADY_ENROLLED: "auth/second-factor-already-in-use"; - readonly SECOND_FACTOR_LIMIT_EXCEEDED: "auth/maximum-second-factor-count-exceeded"; - readonly TENANT_ID_MISMATCH: "auth/tenant-id-mismatch"; - readonly TIMEOUT: "auth/timeout"; - readonly TOKEN_EXPIRED: "auth/user-token-expired"; - readonly TOO_MANY_ATTEMPTS_TRY_LATER: "auth/too-many-requests"; - readonly UNAUTHORIZED_DOMAIN: "auth/unauthorized-continue-uri"; - readonly UNSUPPORTED_FIRST_FACTOR: "auth/unsupported-first-factor"; - readonly UNSUPPORTED_PERSISTENCE: "auth/unsupported-persistence-type"; - readonly UNSUPPORTED_TENANT_OPERATION: "auth/unsupported-tenant-operation"; - readonly UNVERIFIED_EMAIL: "auth/unverified-email"; - readonly USER_CANCELLED: "auth/user-cancelled"; - readonly USER_DELETED: "auth/user-not-found"; - readonly USER_DISABLED: "auth/user-disabled"; - readonly USER_MISMATCH: "auth/user-mismatch"; - readonly USER_SIGNED_OUT: "auth/user-signed-out"; - readonly WEAK_PASSWORD: "auth/weak-password"; - readonly WEB_STORAGE_UNSUPPORTED: "auth/web-storage-unsupported"; - readonly ALREADY_INITIALIZED: "auth/already-initialized"; -} -``` - -## browserLocalPersistence - -An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type `LOCAL` using `localStorage` for the underlying storage. - -Signature: - -```typescript -browserLocalPersistence: Persistence -``` - -## browserPopupRedirectResolver - -An implementation of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) suitable for browser based applications. - -Signature: - -```typescript -browserPopupRedirectResolver: PopupRedirectResolver -``` - -## browserSessionPersistence - -An implementation of [Persistence](./auth.persistence.md#persistence_interface) of `SESSION` using `sessionStorage` for the underlying storage. - -Signature: - -```typescript -browserSessionPersistence: Persistence -``` - -## debugErrorMap - -A verbose error map with detailed descriptions for most error codes. - -See discussion at [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) - -Signature: - -```typescript -debugErrorMap: AuthErrorMap -``` - -## FactorId - -An enum of factors that may be used for multifactor authentication. - -Signature: - -```typescript -FactorId: { - readonly PHONE: "phone"; -} -``` - -## indexedDBLocalPersistence - -An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type `LOCAL` using `indexedDB` for the underlying storage. - -Signature: - -```typescript -indexedDBLocalPersistence: Persistence -``` - -## inMemoryPersistence - -An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type 'NONE'. - -Signature: - -```typescript -inMemoryPersistence: Persistence -``` - -## OperationType - -Enumeration of supported operation types. - -Signature: - -```typescript -OperationType: { - readonly LINK: "link"; - readonly REAUTHENTICATE: "reauthenticate"; - readonly SIGN_IN: "signIn"; -} -``` - -## prodErrorMap - -A minimal error map with all verbose error messages stripped. - -See discussion at [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) - -Signature: - -```typescript -prodErrorMap: AuthErrorMap -``` - -## ProviderId - -Enumeration of supported providers. - -Signature: - -```typescript -ProviderId: { - readonly FACEBOOK: "facebook.com"; - readonly GITHUB: "github.com"; - readonly GOOGLE: "google.com"; - readonly PASSWORD: "password"; - readonly PHONE: "phone"; - readonly TWITTER: "twitter.com"; -} -``` - -## SignInMethod - -Enumeration of supported sign-in methods. - -Signature: - -```typescript -SignInMethod: { - readonly EMAIL_LINK: "emailLink"; - readonly EMAIL_PASSWORD: "password"; - readonly FACEBOOK: "facebook.com"; - readonly GITHUB: "github.com"; - readonly GOOGLE: "google.com"; - readonly PHONE: "phone"; - readonly TWITTER: "twitter.com"; -} -``` - -## CustomParameters - -Map of OAuth Custom Parameters. - -Signature: - -```typescript -export declare type CustomParameters = Record; -``` - -## NextOrObserver - -Type definition for an event callback. - -Signature: - -```typescript -export declare type NextOrObserver = NextFn | Observer; -``` - -## PhoneInfoOptions - -The information required to verify the ownership of a phone number. - -The information that's required depends on whether you are doing single-factor sign-in, multi-factor enrollment or multi-factor sign-in. - -Signature: - -```typescript -export declare type PhoneInfoOptions = PhoneSingleFactorInfoOptions | PhoneMultiFactorEnrollInfoOptions | PhoneMultiFactorSignInInfoOptions; -``` - -## UserProfile - -User profile used in [AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface). - -Signature: - -```typescript -export declare type UserProfile = Record; -``` diff --git a/docs-devsite/auth.multifactorassertion.md b/docs-devsite/auth.multifactorassertion.md deleted file mode 100644 index d7937ec1f64..00000000000 --- a/docs-devsite/auth.multifactorassertion.md +++ /dev/null @@ -1,37 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# MultiFactorAssertion interface -The base class for asserting ownership of a second factor. - -This is used to facilitate enrollment of a second factor on an existing user or sign-in of a user who already verified the first factor. - -Signature: - -```typescript -export interface MultiFactorAssertion -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [factorId](./auth.multifactorassertion.md#multifactorassertionfactorid) | typeof [FactorIdMap](./auth.md#factorid)\[keyof typeof [FactorIdMap](./auth.md#factorid)\] | The identifier of the second factor. | - -## MultiFactorAssertion.factorId - -The identifier of the second factor. - -Signature: - -```typescript -readonly factorId: typeof FactorIdMap[keyof typeof FactorIdMap]; -``` diff --git a/docs-devsite/auth.multifactorerror.md b/docs-devsite/auth.multifactorerror.md deleted file mode 100644 index a13276f5a61..00000000000 --- a/docs-devsite/auth.multifactorerror.md +++ /dev/null @@ -1,67 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# MultiFactorError interface -The error thrown when the user needs to provide a second factor to sign in successfully. - -The error code for this error is `auth/multi-factor-auth-required`. - -Signature: - -```typescript -export interface MultiFactorError extends AuthError -``` -Extends: [AuthError](./auth.autherror.md#autherror_interface) - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [customData](./auth.multifactorerror.md#multifactorerrorcustomdata) | [AuthError](./auth.autherror.md#autherror_interface)\['customData'\] & { readonly operationType: typeof [OperationTypeMap](./auth.md#operationtype)\[keyof typeof [OperationTypeMap](./auth.md#operationtype)\]; } | Details about the MultiFactorError. | - -## MultiFactorError.customData - -Details about the MultiFactorError. - -Signature: - -```typescript -readonly customData: AuthError['customData'] & { - readonly operationType: typeof OperationTypeMap[keyof typeof OperationTypeMap]; - }; -``` - -### Example - - -```javascript -let resolver; -let multiFactorHints; - -signInWithEmailAndPassword(auth, email, password) - .then((result) => { - // User signed in. No 2nd factor challenge is needed. - }) - .catch((error) => { - if (error.code == 'auth/multi-factor-auth-required') { - resolver = getMultiFactorResolver(auth, error); - multiFactorHints = resolver.hints; - } else { - // Handle other errors. - } - }); - -// Obtain a multiFactorAssertion by verifying the second factor. - -const userCredential = await resolver.resolveSignIn(multiFactorAssertion); - -``` - diff --git a/docs-devsite/auth.multifactorinfo.md b/docs-devsite/auth.multifactorinfo.md deleted file mode 100644 index 80a56164b9a..00000000000 --- a/docs-devsite/auth.multifactorinfo.md +++ /dev/null @@ -1,68 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# MultiFactorInfo interface -A structure containing the information of a second factor entity. - -Signature: - -```typescript -export interface MultiFactorInfo -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [displayName](./auth.multifactorinfo.md#multifactorinfodisplayname) | string \| null | The user friendly name of the current second factor. | -| [enrollmentTime](./auth.multifactorinfo.md#multifactorinfoenrollmenttime) | string | The enrollment date of the second factor formatted as a UTC string. | -| [factorId](./auth.multifactorinfo.md#multifactorinfofactorid) | typeof [FactorIdMap](./auth.md#factorid)\[keyof typeof [FactorIdMap](./auth.md#factorid)\] | The identifier of the second factor. | -| [uid](./auth.multifactorinfo.md#multifactorinfouid) | string | The multi-factor enrollment ID. | - -## MultiFactorInfo.displayName - -The user friendly name of the current second factor. - -Signature: - -```typescript -readonly displayName?: string | null; -``` - -## MultiFactorInfo.enrollmentTime - -The enrollment date of the second factor formatted as a UTC string. - -Signature: - -```typescript -readonly enrollmentTime: string; -``` - -## MultiFactorInfo.factorId - -The identifier of the second factor. - -Signature: - -```typescript -readonly factorId: typeof FactorIdMap[keyof typeof FactorIdMap]; -``` - -## MultiFactorInfo.uid - -The multi-factor enrollment ID. - -Signature: - -```typescript -readonly uid: string; -``` diff --git a/docs-devsite/auth.multifactorresolver.md b/docs-devsite/auth.multifactorresolver.md deleted file mode 100644 index 9d6bc3ebcda..00000000000 --- a/docs-devsite/auth.multifactorresolver.md +++ /dev/null @@ -1,128 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# MultiFactorResolver interface -The class used to facilitate recovery from [MultiFactorError](./auth.multifactorerror.md#multifactorerror_interface) when a user needs to provide a second factor to sign in. - -Signature: - -```typescript -export interface MultiFactorResolver -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [hints](./auth.multifactorresolver.md#multifactorresolverhints) | [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface)\[\] | The list of hints for the second factors needed to complete the sign-in for the current session. | -| [session](./auth.multifactorresolver.md#multifactorresolversession) | [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) | The session identifier for the current sign-in flow, which can be used to complete the second factor sign-in. | - -## Methods - -| Method | Description | -| --- | --- | -| [resolveSignIn(assertion)](./auth.multifactorresolver.md#multifactorresolverresolvesignin) | A helper function to help users complete sign in with a second factor using an [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) confirming the user successfully completed the second factor challenge. | - -## MultiFactorResolver.hints - -The list of hints for the second factors needed to complete the sign-in for the current session. - -Signature: - -```typescript -readonly hints: MultiFactorInfo[]; -``` - -## MultiFactorResolver.session - -The session identifier for the current sign-in flow, which can be used to complete the second factor sign-in. - -Signature: - -```typescript -readonly session: MultiFactorSession; -``` - -## MultiFactorResolver.resolveSignIn() - -A helper function to help users complete sign in with a second factor using an [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) confirming the user successfully completed the second factor challenge. - -Signature: - -```typescript -resolveSignIn(assertion: MultiFactorAssertion): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| assertion | [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) | The multi-factor assertion to resolve sign-in with. | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -The promise that resolves with the user credential object. - -### Example - - -```javascript -const phoneAuthCredential = PhoneAuthProvider.credential(verificationId, verificationCode); -const multiFactorAssertion = PhoneMultiFactorGenerator.assertion(phoneAuthCredential); -const userCredential = await resolver.resolveSignIn(multiFactorAssertion); - -``` - -### Example - - -```javascript -let resolver; -let multiFactorHints; - -signInWithEmailAndPassword(auth, email, password) - .then((result) => { - // User signed in. No 2nd factor challenge is needed. - }) - .catch((error) => { - if (error.code == 'auth/multi-factor-auth-required') { - resolver = getMultiFactorResolver(auth, error); - // Show UI to let user select second factor. - multiFactorHints = resolver.hints; - } else { - // Handle other errors. - } - }); - -// The enrolled second factors that can be used to complete -// sign-in are returned in the `MultiFactorResolver.hints` list. -// UI needs to be presented to allow the user to select a second factor -// from that list. - -const selectedHint = // ; selected from multiFactorHints -const phoneAuthProvider = new PhoneAuthProvider(auth); -const phoneInfoOptions = { - multiFactorHint: selectedHint, - session: resolver.session -}; -const verificationId = phoneAuthProvider.verifyPhoneNumber(phoneInfoOptions, appVerifier); -// Store `verificationId` and show UI to let user enter verification code. - -// UI to enter verification code and continue. -// Continue button click handler -const phoneAuthCredential = PhoneAuthProvider.credential(verificationId, verificationCode); -const multiFactorAssertion = PhoneMultiFactorGenerator.assertion(phoneAuthCredential); -const userCredential = await resolver.resolveSignIn(multiFactorAssertion); - -``` - diff --git a/docs-devsite/auth.multifactorsession.md b/docs-devsite/auth.multifactorsession.md deleted file mode 100644 index 9ad2d0a1682..00000000000 --- a/docs-devsite/auth.multifactorsession.md +++ /dev/null @@ -1,19 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# MultiFactorSession interface -An interface defining the multi-factor session object used for enrolling a second factor on a user or helping sign in an enrolled user with a second factor. - -Signature: - -```typescript -export interface MultiFactorSession -``` diff --git a/docs-devsite/auth.multifactoruser.md b/docs-devsite/auth.multifactoruser.md deleted file mode 100644 index 9f25e4174fc..00000000000 --- a/docs-devsite/auth.multifactoruser.md +++ /dev/null @@ -1,161 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# MultiFactorUser interface -An interface that defines the multi-factor related properties and operations pertaining to a [User](./auth.user.md#user_interface). - -Signature: - -```typescript -export interface MultiFactorUser -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [enrolledFactors](./auth.multifactoruser.md#multifactoruserenrolledfactors) | [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface)\[\] | Returns a list of the user's enrolled second factors. | - -## Methods - -| Method | Description | -| --- | --- | -| [enroll(assertion, displayName)](./auth.multifactoruser.md#multifactoruserenroll) | Enrolls a second factor as identified by the [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) for the user. | -| [getSession()](./auth.multifactoruser.md#multifactorusergetsession) | Returns the session identifier for a second factor enrollment operation. This is used to identify the user trying to enroll a second factor. | -| [unenroll(option)](./auth.multifactoruser.md#multifactoruserunenroll) | Unenrolls the specified second factor. | - -## MultiFactorUser.enrolledFactors - -Returns a list of the user's enrolled second factors. - -Signature: - -```typescript -readonly enrolledFactors: MultiFactorInfo[]; -``` - -## MultiFactorUser.enroll() - -Enrolls a second factor as identified by the [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) for the user. - -On resolution, the user tokens are updated to reflect the change in the JWT payload. Accepts an additional display name parameter used to identify the second factor to the end user. Recent re-authentication is required for this operation to succeed. On successful enrollment, existing Firebase sessions (refresh tokens) are revoked. When a new factor is enrolled, an email notification is sent to the user’s email. - -Signature: - -```typescript -enroll(assertion: MultiFactorAssertion, displayName?: string | null): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| assertion | [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) | The multi-factor assertion to enroll with. | -| displayName | string \| null | The display name of the second factor. | - -Returns: - -Promise<void> - -### Example - - -```javascript -const multiFactorUser = multiFactor(auth.currentUser); -const multiFactorSession = await multiFactorUser.getSession(); - -// Send verification code. -const phoneAuthProvider = new PhoneAuthProvider(auth); -const phoneInfoOptions = { - phoneNumber: phoneNumber, - session: multiFactorSession -}; -const verificationId = await phoneAuthProvider.verifyPhoneNumber(phoneInfoOptions, appVerifier); - -// Obtain verification code from user. -const phoneAuthCredential = PhoneAuthProvider.credential(verificationId, verificationCode); -const multiFactorAssertion = PhoneMultiFactorGenerator.assertion(phoneAuthCredential); -await multiFactorUser.enroll(multiFactorAssertion); -// Second factor enrolled. - -``` - -## MultiFactorUser.getSession() - -Returns the session identifier for a second factor enrollment operation. This is used to identify the user trying to enroll a second factor. - -Signature: - -```typescript -getSession(): Promise; -``` -Returns: - -Promise<[MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface)> - -The promise that resolves with the [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface). - -### Example - - -```javascript -const multiFactorUser = multiFactor(auth.currentUser); -const multiFactorSession = await multiFactorUser.getSession(); - -// Send verification code. -const phoneAuthProvider = new PhoneAuthProvider(auth); -const phoneInfoOptions = { - phoneNumber: phoneNumber, - session: multiFactorSession -}; -const verificationId = await phoneAuthProvider.verifyPhoneNumber(phoneInfoOptions, appVerifier); - -// Obtain verification code from user. -const phoneAuthCredential = PhoneAuthProvider.credential(verificationId, verificationCode); -const multiFactorAssertion = PhoneMultiFactorGenerator.assertion(phoneAuthCredential); -await multiFactorUser.enroll(multiFactorAssertion); - -``` - -## MultiFactorUser.unenroll() - -Unenrolls the specified second factor. - -To specify the factor to remove, pass a [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) object (retrieved from [MultiFactorUser.enrolledFactors](./auth.multifactoruser.md#multifactoruserenrolledfactors)) or the factor's UID string. Sessions are not revoked when the account is unenrolled. An email notification is likely to be sent to the user notifying them of the change. Recent re-authentication is required for this operation to succeed. When an existing factor is unenrolled, an email notification is sent to the user’s email. - -Signature: - -```typescript -unenroll(option: MultiFactorInfo | string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| option | [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) \| string | The multi-factor option to unenroll. | - -Returns: - -Promise<void> - -- A `Promise` which resolves when the unenroll operation is complete. - -### Example - - -```javascript -const multiFactorUser = multiFactor(auth.currentUser); -// Present user the option to choose which factor to unenroll. -await multiFactorUser.unenroll(multiFactorUser.enrolledFactors[i]) - -``` - diff --git a/docs-devsite/auth.oauthcredential.md b/docs-devsite/auth.oauthcredential.md deleted file mode 100644 index dc3855e01a1..00000000000 --- a/docs-devsite/auth.oauthcredential.md +++ /dev/null @@ -1,105 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# OAuthCredential class -Represents the OAuth credentials returned by an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). - -Implementations specify the details about each auth provider's credential requirements. - -Signature: - -```typescript -export declare class OAuthCredential extends AuthCredential -``` -Extends: [AuthCredential](./auth.authcredential.md#authcredential_class) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [accessToken](./auth.oauthcredential.md#oauthcredentialaccesstoken) | | string | The OAuth access token associated with the credential if it belongs to an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class), such as facebook.com, twitter.com, etc. | -| [idToken](./auth.oauthcredential.md#oauthcredentialidtoken) | | string | The OAuth ID token associated with the credential if it belongs to an OIDC provider, such as google.com. | -| [secret](./auth.oauthcredential.md#oauthcredentialsecret) | | string | The OAuth access token secret associated with the credential if it belongs to an OAuth 1.0 provider, such as twitter.com. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [fromJSON(json)](./auth.oauthcredential.md#oauthcredentialfromjson) | static | Static method to deserialize a JSON representation of an object into an [AuthCredential](./auth.authcredential.md#authcredential_class). | -| [toJSON()](./auth.oauthcredential.md#oauthcredentialtojson) | | Returns a JSON-serializable representation of this object. | - -## OAuthCredential.accessToken - -The OAuth access token associated with the credential if it belongs to an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class), such as `facebook.com`, `twitter.com`, etc. - -Signature: - -```typescript -accessToken?: string; -``` - -## OAuthCredential.idToken - -The OAuth ID token associated with the credential if it belongs to an OIDC provider, such as `google.com`. - -Signature: - -```typescript -idToken?: string; -``` - -## OAuthCredential.secret - -The OAuth access token secret associated with the credential if it belongs to an OAuth 1.0 provider, such as `twitter.com`. - -Signature: - -```typescript -secret?: string; -``` - -## OAuthCredential.fromJSON() - -Static method to deserialize a JSON representation of an object into an [AuthCredential](./auth.authcredential.md#authcredential_class). - -Signature: - -```typescript -static fromJSON(json: string | object): OAuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| json | string \| object | Input can be either Object or the stringified representation of the object. When string is provided, JSON.parse would be called first. | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null - -If the JSON input does not represent an [AuthCredential](./auth.authcredential.md#authcredential_class), null is returned. - -## OAuthCredential.toJSON() - -Returns a JSON-serializable representation of this object. - -Signature: - -```typescript -toJSON(): object; -``` -Returns: - -object - -a JSON-serializable representation of this object. - diff --git a/docs-devsite/auth.oauthcredentialoptions.md b/docs-devsite/auth.oauthcredentialoptions.md deleted file mode 100644 index 0389c534c17..00000000000 --- a/docs-devsite/auth.oauthcredentialoptions.md +++ /dev/null @@ -1,61 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# OAuthCredentialOptions interface -Defines the options for initializing an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). - -For ID tokens with nonce claim, the raw nonce has to also be provided. - -Signature: - -```typescript -export interface OAuthCredentialOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [accessToken](./auth.oauthcredentialoptions.md#oauthcredentialoptionsaccesstoken) | string | The OAuth access token used to initialize the [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). | -| [idToken](./auth.oauthcredentialoptions.md#oauthcredentialoptionsidtoken) | string | The OAuth ID token used to initialize the [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). | -| [rawNonce](./auth.oauthcredentialoptions.md#oauthcredentialoptionsrawnonce) | string | The raw nonce associated with the ID token. | - -## OAuthCredentialOptions.accessToken - -The OAuth access token used to initialize the [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). - -Signature: - -```typescript -accessToken?: string; -``` - -## OAuthCredentialOptions.idToken - -The OAuth ID token used to initialize the [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). - -Signature: - -```typescript -idToken?: string; -``` - -## OAuthCredentialOptions.rawNonce - -The raw nonce associated with the ID token. - -It is required when an ID token with a nonce field is provided. The SHA-256 hash of the raw nonce must match the nonce field in the ID token. - -Signature: - -```typescript -rawNonce?: string; -``` diff --git a/docs-devsite/auth.oauthprovider.md b/docs-devsite/auth.oauthprovider.md deleted file mode 100644 index 30141fcce40..00000000000 --- a/docs-devsite/auth.oauthprovider.md +++ /dev/null @@ -1,168 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# OAuthProvider class -Provider for generating generic [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). - -Signature: - -```typescript -export declare class OAuthProvider extends BaseOAuthProvider -``` -Extends: BaseOAuthProvider - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [credential(params)](./auth.oauthprovider.md#oauthprovidercredential) | | Creates a [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a generic OAuth provider's access token or ID token. | -| [credentialFromError(error)](./auth.oauthprovider.md#oauthprovidercredentialfromerror) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. | -| [credentialFromJSON(json)](./auth.oauthprovider.md#oauthprovidercredentialfromjson) | static | Creates an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a JSON string or a plain object. | -| [credentialFromResult(userCredential)](./auth.oauthprovider.md#oauthprovidercredentialfromresult) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). | - -## OAuthProvider.credential() - -Creates a [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a generic OAuth provider's access token or ID token. - -The raw nonce is required when an ID token with a nonce field is provided. The SHA-256 hash of the raw nonce must match the nonce field in the ID token. - -Signature: - -```typescript -credential(params: OAuthCredentialOptions): OAuthCredential; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| params | [OAuthCredentialOptions](./auth.oauthcredentialoptions.md#oauthcredentialoptions_interface) | Either the options object containing the ID token, access token and raw nonce or the ID token string. | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) - -### Example - - -```javascript -// `googleUser` from the onsuccess Google Sign In callback. -// Initialize a generate OAuth provider with a `google.com` providerId. -const provider = new OAuthProvider('google.com'); -const credential = provider.credential({ - idToken: googleUser.getAuthResponse().id_token, -}); -const result = await signInWithCredential(credential); - -``` - -## OAuthProvider.credentialFromError() - -Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. - -Signature: - -```typescript -static credentialFromError(error: FirebaseError): OAuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null - -## OAuthProvider.credentialFromJSON() - -Creates an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a JSON string or a plain object. - -Signature: - -```typescript -static credentialFromJSON(json: object | string): OAuthCredential; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| json | object \| string | A plain object or a JSON string | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) - -## OAuthProvider.credentialFromResult() - -Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). - -Signature: - -```typescript -static credentialFromResult(userCredential: UserCredential): OAuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null - -### Example 1 - - -```javascript -// Sign in using a redirect. -const provider = new OAuthProvider('google.com'); -// Start a sign in process for an unauthenticated user. -provider.addScope('profile'); -provider.addScope('email'); -await signInWithRedirect(auth, provider); -// This will trigger a full page redirect away from your app - -// After returning from the redirect when your app initializes you can obtain the result -const result = await getRedirectResult(auth); -if (result) { - // This is the signed-in user - const user = result.user; - // This gives you a OAuth Access Token for the provider. - const credential = provider.credentialFromResult(auth, result); - const token = credential.accessToken; -} - -``` - -### Example 2 - - -```javascript -// Sign in using a popup. -const provider = new OAuthProvider('google.com'); -provider.addScope('profile'); -provider.addScope('email'); -const result = await signInWithPopup(auth, provider); - -// The signed-in user info. -const user = result.user; -// This gives you a OAuth Access Token for the provider. -const credential = provider.credentialFromResult(auth, result); -const token = credential.accessToken; - -``` - diff --git a/docs-devsite/auth.parsedtoken.md b/docs-devsite/auth.parsedtoken.md deleted file mode 100644 index 7892b135536..00000000000 --- a/docs-devsite/auth.parsedtoken.md +++ /dev/null @@ -1,83 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ParsedToken interface -Interface representing a parsed ID token. - -Signature: - -```typescript -export interface ParsedToken -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [auth\_time](./auth.parsedtoken.md#parsedtokenauth_time) | string | Time at which authentication was performed. | -| [exp](./auth.parsedtoken.md#parsedtokenexp) | string | Expiration time of the token. | -| [firebase](./auth.parsedtoken.md#parsedtokenfirebase) | { 'sign\_in\_provider'?: string; 'sign\_in\_second\_factor'?: string; 'identities'?: Record<string, string>; } | Firebase specific claims, containing the provider(s) used to authenticate the user. | -| [iat](./auth.parsedtoken.md#parsedtokeniat) | string | Issuance time of the token. | -| [sub](./auth.parsedtoken.md#parsedtokensub) | string | UID of the user. | - -## ParsedToken.auth\_time - -Time at which authentication was performed. - -Signature: - -```typescript -'auth_time'?: string; -``` - -## ParsedToken.exp - -Expiration time of the token. - -Signature: - -```typescript -'exp'?: string; -``` - -## ParsedToken.firebase - -Firebase specific claims, containing the provider(s) used to authenticate the user. - -Signature: - -```typescript -'firebase'?: { - 'sign_in_provider'?: string; - 'sign_in_second_factor'?: string; - 'identities'?: Record; - }; -``` - -## ParsedToken.iat - -Issuance time of the token. - -Signature: - -```typescript -'iat'?: string; -``` - -## ParsedToken.sub - -UID of the user. - -Signature: - -```typescript -'sub'?: string; -``` diff --git a/docs-devsite/auth.persistence.md b/docs-devsite/auth.persistence.md deleted file mode 100644 index b3f9ecb11e1..00000000000 --- a/docs-devsite/auth.persistence.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Persistence interface -An interface covering the possible persistence mechanism types. - -Signature: - -```typescript -export interface Persistence -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [type](./auth.persistence.md#persistencetype) | 'SESSION' \| 'LOCAL' \| 'NONE' | Type of Persistence. - 'SESSION' is used for temporary persistence such as sessionStorage. - 'LOCAL' is used for long term persistence such as localStorage or IndexedDB. - 'NONE' is used for in-memory, or no persistence. | - -## Persistence.type - -Type of Persistence. - 'SESSION' is used for temporary persistence such as `sessionStorage`. - 'LOCAL' is used for long term persistence such as `localStorage` or `IndexedDB`. - 'NONE' is used for in-memory, or no persistence. - -Signature: - -```typescript -readonly type: 'SESSION' | 'LOCAL' | 'NONE'; -``` diff --git a/docs-devsite/auth.phoneauthcredential.md b/docs-devsite/auth.phoneauthcredential.md deleted file mode 100644 index 44a85db5254..00000000000 --- a/docs-devsite/auth.phoneauthcredential.md +++ /dev/null @@ -1,63 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# PhoneAuthCredential class -Represents the credentials returned by [PhoneAuthProvider](./auth.phoneauthprovider.md#phoneauthprovider_class). - -Signature: - -```typescript -export declare class PhoneAuthCredential extends AuthCredential -``` -Extends: [AuthCredential](./auth.authcredential.md#authcredential_class) - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [fromJSON(json)](./auth.phoneauthcredential.md#phoneauthcredentialfromjson) | static | Generates a phone credential based on a plain object or a JSON string. | -| [toJSON()](./auth.phoneauthcredential.md#phoneauthcredentialtojson) | | Returns a JSON-serializable representation of this object. | - -## PhoneAuthCredential.fromJSON() - -Generates a phone credential based on a plain object or a JSON string. - -Signature: - -```typescript -static fromJSON(json: object | string): PhoneAuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| json | object \| string | | - -Returns: - -[PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class) \| null - -## PhoneAuthCredential.toJSON() - -Returns a JSON-serializable representation of this object. - -Signature: - -```typescript -toJSON(): object; -``` -Returns: - -object - -a JSON-serializable representation of this object. - diff --git a/docs-devsite/auth.phoneauthprovider.md b/docs-devsite/auth.phoneauthprovider.md deleted file mode 100644 index 41e743386de..00000000000 --- a/docs-devsite/auth.phoneauthprovider.md +++ /dev/null @@ -1,256 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# PhoneAuthProvider class -Provider for generating an [PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class). - -Signature: - -```typescript -export declare class PhoneAuthProvider -``` - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(auth)](./auth.phoneauthprovider.md#phoneauthproviderconstructor) | | Constructs a new instance of the PhoneAuthProvider class | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [PHONE\_SIGN\_IN\_METHOD](./auth.phoneauthprovider.md#phoneauthproviderphone_sign_in_method) | static | 'phone' | Always set to [SignInMethod](./auth.md#signinmethod).PHONE. | -| [PROVIDER\_ID](./auth.phoneauthprovider.md#phoneauthproviderprovider_id) | static | 'phone' | Always set to [ProviderId](./auth.md#providerid).PHONE. | -| [providerId](./auth.phoneauthprovider.md#phoneauthproviderproviderid) | | "phone" | Always set to [ProviderId](./auth.md#providerid).PHONE. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [credential(verificationId, verificationCode)](./auth.phoneauthprovider.md#phoneauthprovidercredential) | static | Creates a phone auth credential, given the verification ID from [PhoneAuthProvider.verifyPhoneNumber()](./auth.phoneauthprovider.md#phoneauthproviderverifyphonenumber) and the code that was sent to the user's mobile device. | -| [credentialFromError(error)](./auth.phoneauthprovider.md#phoneauthprovidercredentialfromerror) | static | Returns an [AuthCredential](./auth.authcredential.md#authcredential_class) when passed an error. | -| [credentialFromResult(userCredential)](./auth.phoneauthprovider.md#phoneauthprovidercredentialfromresult) | static | Generates an [AuthCredential](./auth.authcredential.md#authcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). | -| [verifyPhoneNumber(phoneOptions, applicationVerifier)](./auth.phoneauthprovider.md#phoneauthproviderverifyphonenumber) | | Starts a phone number authentication flow by sending a verification code to the given phone number. | - -## PhoneAuthProvider.(constructor) - -Constructs a new instance of the `PhoneAuthProvider` class - -Signature: - -```typescript -constructor(auth: Auth); -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The Firebase [Auth](./auth.auth.md#auth_interface) instance in which sign-ins should occur. | - -## PhoneAuthProvider.PHONE\_SIGN\_IN\_METHOD - -Always set to [SignInMethod](./auth.md#signinmethod).PHONE. - -Signature: - -```typescript -static readonly PHONE_SIGN_IN_METHOD: 'phone'; -``` - -## PhoneAuthProvider.PROVIDER\_ID - -Always set to [ProviderId](./auth.md#providerid).PHONE. - -Signature: - -```typescript -static readonly PROVIDER_ID: 'phone'; -``` - -## PhoneAuthProvider.providerId - -Always set to [ProviderId](./auth.md#providerid).PHONE. - -Signature: - -```typescript -readonly providerId: "phone"; -``` - -## PhoneAuthProvider.credential() - -Creates a phone auth credential, given the verification ID from [PhoneAuthProvider.verifyPhoneNumber()](./auth.phoneauthprovider.md#phoneauthproviderverifyphonenumber) and the code that was sent to the user's mobile device. - -Signature: - -```typescript -static credential(verificationId: string, verificationCode: string): PhoneAuthCredential; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| verificationId | string | The verification ID returned from [PhoneAuthProvider.verifyPhoneNumber()](./auth.phoneauthprovider.md#phoneauthproviderverifyphonenumber). | -| verificationCode | string | The verification code sent to the user's mobile device. | - -Returns: - -[PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class) - -The auth provider credential. - -### Example 1 - - -```javascript -const provider = new PhoneAuthProvider(auth); -const verificationId = provider.verifyPhoneNumber(phoneNumber, applicationVerifier); -// Obtain verificationCode from the user. -const authCredential = PhoneAuthProvider.credential(verificationId, verificationCode); -const userCredential = signInWithCredential(auth, authCredential); - -``` - -### Example 2 - -An alternative flow is provided using the `signInWithPhoneNumber` method. - -```javascript -const confirmationResult = await signInWithPhoneNumber(auth, phoneNumber, applicationVerifier); -// Obtain verificationCode from the user. -const userCredential = await confirmationResult.confirm(verificationCode); - -``` - -## PhoneAuthProvider.credentialFromError() - -Returns an [AuthCredential](./auth.authcredential.md#authcredential_class) when passed an error. - -This method works for errors like `auth/account-exists-with-different-credentials`. This is useful for recovering when attempting to set a user's phone number but the number in question is already tied to another account. For example, the following code tries to update the current user's phone number, and if that fails, links the user with the account associated with that number: - -```js -const provider = new PhoneAuthProvider(auth); -const verificationId = await provider.verifyPhoneNumber(number, verifier); -try { - const code = ''; // Prompt the user for the verification code - await updatePhoneNumber( - auth.currentUser, - PhoneAuthProvider.credential(verificationId, code)); -} catch (e) { - if ((e as FirebaseError)?.code === 'auth/account-exists-with-different-credential') { - const cred = PhoneAuthProvider.credentialFromError(e); - await linkWithCredential(auth.currentUser, cred); - } -} - -// At this point, auth.currentUser.phoneNumber === number. - -``` - -Signature: - -```typescript -static credentialFromError(error: FirebaseError): AuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | The error to generate a credential from. | - -Returns: - -[AuthCredential](./auth.authcredential.md#authcredential_class) \| null - -## PhoneAuthProvider.credentialFromResult() - -Generates an [AuthCredential](./auth.authcredential.md#authcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). - -Signature: - -```typescript -static credentialFromResult(userCredential: UserCredential): AuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | - -Returns: - -[AuthCredential](./auth.authcredential.md#authcredential_class) \| null - -## PhoneAuthProvider.verifyPhoneNumber() - -Starts a phone number authentication flow by sending a verification code to the given phone number. - -Signature: - -```typescript -verifyPhoneNumber(phoneOptions: PhoneInfoOptions | string, applicationVerifier: ApplicationVerifier): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| phoneOptions | [PhoneInfoOptions](./auth.md#phoneinfooptions) \| string | | -| applicationVerifier | [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) | For abuse prevention, this method also requires a [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface). This SDK includes a reCAPTCHA-based implementation, [RecaptchaVerifier](./auth.recaptchaverifier.md#recaptchaverifier_class). | - -Returns: - -Promise<string> - -A Promise for a verification ID that can be passed to [PhoneAuthProvider.credential()](./auth.phoneauthprovider.md#phoneauthprovidercredential) to identify this flow.. - -### Example 1 - - -```javascript -const provider = new PhoneAuthProvider(auth); -const verificationId = await provider.verifyPhoneNumber(phoneNumber, applicationVerifier); -// Obtain verificationCode from the user. -const authCredential = PhoneAuthProvider.credential(verificationId, verificationCode); -const userCredential = await signInWithCredential(auth, authCredential); - -``` - -### Example 2 - -An alternative flow is provided using the `signInWithPhoneNumber` method. - -```javascript -const confirmationResult = signInWithPhoneNumber(auth, phoneNumber, applicationVerifier); -// Obtain verificationCode from the user. -const userCredential = confirmationResult.confirm(verificationCode); - -``` - -### Example - - -```javascript -// 'recaptcha-container' is the ID of an element in the DOM. -const applicationVerifier = new RecaptchaVerifier('recaptcha-container'); -const provider = new PhoneAuthProvider(auth); -const verificationId = await provider.verifyPhoneNumber('+16505550101', applicationVerifier); -// Obtain the verificationCode from the user. -const phoneCredential = PhoneAuthProvider.credential(verificationId, verificationCode); -const userCredential = await signInWithCredential(auth, phoneCredential); - -``` - diff --git a/docs-devsite/auth.phonemultifactorassertion.md b/docs-devsite/auth.phonemultifactorassertion.md deleted file mode 100644 index 1f6afd2410f..00000000000 --- a/docs-devsite/auth.phonemultifactorassertion.md +++ /dev/null @@ -1,21 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# PhoneMultiFactorAssertion interface -The class for asserting ownership of a phone second factor. Provided by [PhoneMultiFactorGenerator.assertion()](./auth.phonemultifactorgenerator.md#phonemultifactorgeneratorassertion). - -Signature: - -```typescript -export interface PhoneMultiFactorAssertion extends MultiFactorAssertion -``` -Extends: [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) - diff --git a/docs-devsite/auth.phonemultifactorenrollinfooptions.md b/docs-devsite/auth.phonemultifactorenrollinfooptions.md deleted file mode 100644 index f36cfc29d8d..00000000000 --- a/docs-devsite/auth.phonemultifactorenrollinfooptions.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# PhoneMultiFactorEnrollInfoOptions interface -Options used for enrolling a second factor. - -Signature: - -```typescript -export interface PhoneMultiFactorEnrollInfoOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [phoneNumber](./auth.phonemultifactorenrollinfooptions.md#phonemultifactorenrollinfooptionsphonenumber) | string | Phone number to send a verification code to. | -| [session](./auth.phonemultifactorenrollinfooptions.md#phonemultifactorenrollinfooptionssession) | [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) | The [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) obtained via [MultiFactorUser.getSession()](./auth.multifactoruser.md#multifactorusergetsession). | - -## PhoneMultiFactorEnrollInfoOptions.phoneNumber - -Phone number to send a verification code to. - -Signature: - -```typescript -phoneNumber: string; -``` - -## PhoneMultiFactorEnrollInfoOptions.session - -The [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) obtained via [MultiFactorUser.getSession()](./auth.multifactoruser.md#multifactorusergetsession). - -Signature: - -```typescript -session: MultiFactorSession; -``` diff --git a/docs-devsite/auth.phonemultifactorgenerator.md b/docs-devsite/auth.phonemultifactorgenerator.md deleted file mode 100644 index a59d34814bf..00000000000 --- a/docs-devsite/auth.phonemultifactorgenerator.md +++ /dev/null @@ -1,64 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# PhoneMultiFactorGenerator class -Provider for generating a [PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface). - -Signature: - -```typescript -export declare class PhoneMultiFactorGenerator -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [FACTOR\_ID](./auth.phonemultifactorgenerator.md#phonemultifactorgeneratorfactor_id) | static | string | The identifier of the phone second factor: phone. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [assertion(credential)](./auth.phonemultifactorgenerator.md#phonemultifactorgeneratorassertion) | static | Provides a [PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface) to confirm ownership of the phone second factor. | - -## PhoneMultiFactorGenerator.FACTOR\_ID - -The identifier of the phone second factor: `phone`. - -Signature: - -```typescript -static FACTOR_ID: string; -``` - -## PhoneMultiFactorGenerator.assertion() - -Provides a [PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface) to confirm ownership of the phone second factor. - -Signature: - -```typescript -static assertion(credential: PhoneAuthCredential): PhoneMultiFactorAssertion; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| credential | [PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class) | | - -Returns: - -[PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface) - -A [PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface) which can be used with [MultiFactorResolver.resolveSignIn()](./auth.multifactorresolver.md#multifactorresolverresolvesignin) - diff --git a/docs-devsite/auth.phonemultifactorinfo.md b/docs-devsite/auth.phonemultifactorinfo.md deleted file mode 100644 index c12c72b8a55..00000000000 --- a/docs-devsite/auth.phonemultifactorinfo.md +++ /dev/null @@ -1,36 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# PhoneMultiFactorInfo interface -The subclass of the [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) interface for phone number second factors. The `factorId` of this second factor is [FactorId](./auth.md#factorid).PHONE. - -Signature: - -```typescript -export interface PhoneMultiFactorInfo extends MultiFactorInfo -``` -Extends: [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [phoneNumber](./auth.phonemultifactorinfo.md#phonemultifactorinfophonenumber) | string | The phone number associated with the current second factor. | - -## PhoneMultiFactorInfo.phoneNumber - -The phone number associated with the current second factor. - -Signature: - -```typescript -readonly phoneNumber: string; -``` diff --git a/docs-devsite/auth.phonemultifactorsignininfooptions.md b/docs-devsite/auth.phonemultifactorsignininfooptions.md deleted file mode 100644 index 592ef7118b3..00000000000 --- a/docs-devsite/auth.phonemultifactorsignininfooptions.md +++ /dev/null @@ -1,61 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# PhoneMultiFactorSignInInfoOptions interface -Options used for signing in with a second factor. - -Signature: - -```typescript -export interface PhoneMultiFactorSignInInfoOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [multiFactorHint](./auth.phonemultifactorsignininfooptions.md#phonemultifactorsignininfooptionsmultifactorhint) | [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) | The [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) obtained via [MultiFactorResolver.hints](./auth.multifactorresolver.md#multifactorresolverhints).One of multiFactorHint or multiFactorUid is required. | -| [multiFactorUid](./auth.phonemultifactorsignininfooptions.md#phonemultifactorsignininfooptionsmultifactoruid) | string | The uid of the second factor.One of multiFactorHint or multiFactorUid is required. | -| [session](./auth.phonemultifactorsignininfooptions.md#phonemultifactorsignininfooptionssession) | [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) | The [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) obtained via [MultiFactorResolver.session](./auth.multifactorresolver.md#multifactorresolversession). | - -## PhoneMultiFactorSignInInfoOptions.multiFactorHint - -The [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) obtained via [MultiFactorResolver.hints](./auth.multifactorresolver.md#multifactorresolverhints). - -One of `multiFactorHint` or `multiFactorUid` is required. - -Signature: - -```typescript -multiFactorHint?: MultiFactorInfo; -``` - -## PhoneMultiFactorSignInInfoOptions.multiFactorUid - -The uid of the second factor. - -One of `multiFactorHint` or `multiFactorUid` is required. - -Signature: - -```typescript -multiFactorUid?: string; -``` - -## PhoneMultiFactorSignInInfoOptions.session - -The [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) obtained via [MultiFactorResolver.session](./auth.multifactorresolver.md#multifactorresolversession). - -Signature: - -```typescript -session: MultiFactorSession; -``` diff --git a/docs-devsite/auth.phonesinglefactorinfooptions.md b/docs-devsite/auth.phonesinglefactorinfooptions.md deleted file mode 100644 index f7846d0db42..00000000000 --- a/docs-devsite/auth.phonesinglefactorinfooptions.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# PhoneSingleFactorInfoOptions interface -Options used for single-factor sign-in. - -Signature: - -```typescript -export interface PhoneSingleFactorInfoOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [phoneNumber](./auth.phonesinglefactorinfooptions.md#phonesinglefactorinfooptionsphonenumber) | string | Phone number to send a verification code to. | - -## PhoneSingleFactorInfoOptions.phoneNumber - -Phone number to send a verification code to. - -Signature: - -```typescript -phoneNumber: string; -``` diff --git a/docs-devsite/auth.popupredirectresolver.md b/docs-devsite/auth.popupredirectresolver.md deleted file mode 100644 index 67c3274847c..00000000000 --- a/docs-devsite/auth.popupredirectresolver.md +++ /dev/null @@ -1,19 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# PopupRedirectResolver interface -A resolver used for handling DOM specific operations like [signInWithPopup()](./auth.md#signinwithpopup) or [signInWithRedirect()](./auth.md#signinwithredirect). - -Signature: - -```typescript -export interface PopupRedirectResolver -``` diff --git a/docs-devsite/auth.reactnativeasyncstorage.md b/docs-devsite/auth.reactnativeasyncstorage.md deleted file mode 100644 index 231e7d2ed31..00000000000 --- a/docs-devsite/auth.reactnativeasyncstorage.md +++ /dev/null @@ -1,89 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ReactNativeAsyncStorage interface -Interface for a supplied `AsyncStorage`. - -Signature: - -```typescript -export interface ReactNativeAsyncStorage -``` - -## Methods - -| Method | Description | -| --- | --- | -| [getItem(key)](./auth.reactnativeasyncstorage.md#reactnativeasyncstoragegetitem) | Retrieve an item from storage. | -| [removeItem(key)](./auth.reactnativeasyncstorage.md#reactnativeasyncstorageremoveitem) | Remove an item from storage. | -| [setItem(key, value)](./auth.reactnativeasyncstorage.md#reactnativeasyncstoragesetitem) | Persist an item in storage. | - -## ReactNativeAsyncStorage.getItem() - -Retrieve an item from storage. - -Signature: - -```typescript -getItem(key: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| key | string | storage key. | - -Returns: - -Promise<string \| null> - -## ReactNativeAsyncStorage.removeItem() - -Remove an item from storage. - -Signature: - -```typescript -removeItem(key: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| key | string | storage key. | - -Returns: - -Promise<void> - -## ReactNativeAsyncStorage.setItem() - -Persist an item in storage. - -Signature: - -```typescript -setItem(key: string, value: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| key | string | storage key. | -| value | string | storage value. | - -Returns: - -Promise<void> - diff --git a/docs-devsite/auth.recaptchaparameters.md b/docs-devsite/auth.recaptchaparameters.md deleted file mode 100644 index 5d70f1826eb..00000000000 --- a/docs-devsite/auth.recaptchaparameters.md +++ /dev/null @@ -1,23 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# RecaptchaParameters interface -Interface representing reCAPTCHA parameters. - -See the \[reCAPTCHA docs\](https://developers.google.com/recaptcha/docs/display\#render\_param) for the list of accepted parameters. All parameters are accepted except for `sitekey`: Firebase Auth provisions a reCAPTCHA for each project and will configure the site key upon rendering. - -For an invisible reCAPTCHA, set the `size` key to `invisible`. - -Signature: - -```typescript -export interface RecaptchaParameters -``` diff --git a/docs-devsite/auth.recaptchaverifier.md b/docs-devsite/auth.recaptchaverifier.md deleted file mode 100644 index 4f32d489aed..00000000000 --- a/docs-devsite/auth.recaptchaverifier.md +++ /dev/null @@ -1,116 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# RecaptchaVerifier class -An [reCAPTCHA](https://www.google.com/recaptcha/)-based application verifier. - -Signature: - -```typescript -export declare class RecaptchaVerifier implements ApplicationVerifierInternal -``` -Implements: ApplicationVerifierInternal - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(containerOrId, parameters, authExtern)](./auth.recaptchaverifier.md#recaptchaverifierconstructor) | | Constructs a new instance of the RecaptchaVerifier class | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./auth.recaptchaverifier.md#recaptchaverifiertype) | | (not declared) | The application verifier type. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [clear()](./auth.recaptchaverifier.md#recaptchaverifierclear) | | Clears the reCAPTCHA widget from the page and destroys the instance. | -| [render()](./auth.recaptchaverifier.md#recaptchaverifierrender) | | Renders the reCAPTCHA widget on the page. | -| [verify()](./auth.recaptchaverifier.md#recaptchaverifierverify) | | Waits for the user to solve the reCAPTCHA and resolves with the reCAPTCHA token. | - -## RecaptchaVerifier.(constructor) - -Constructs a new instance of the `RecaptchaVerifier` class - -Check the reCAPTCHA docs for a comprehensive list. All parameters are accepted except for the sitekey. Firebase Auth backend provisions a reCAPTCHA for each project and will configure this upon rendering. For an invisible reCAPTCHA, a size key must have the value 'invisible'. - -Signature: - -```typescript -constructor(containerOrId: HTMLElement | string, parameters: RecaptchaParameters, authExtern: Auth); -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| containerOrId | HTMLElement \| string | The reCAPTCHA container parameter. | -| parameters | [RecaptchaParameters](./auth.recaptchaparameters.md#recaptchaparameters_interface) | The optional reCAPTCHA parameters. | -| authExtern | [Auth](./auth.auth.md#auth_interface) | The corresponding Firebase [Auth](./auth.auth.md#auth_interface) instance. | - -## RecaptchaVerifier.type - -The application verifier type. - -For a reCAPTCHA verifier, this is 'recaptcha'. - -Signature: - -```typescript -readonly type = "recaptcha"; -``` - -## RecaptchaVerifier.clear() - -Clears the reCAPTCHA widget from the page and destroys the instance. - -Signature: - -```typescript -clear(): void; -``` -Returns: - -void - -## RecaptchaVerifier.render() - -Renders the reCAPTCHA widget on the page. - -Signature: - -```typescript -render(): Promise; -``` -Returns: - -Promise<number> - -A Promise that resolves with the reCAPTCHA widget ID. - -## RecaptchaVerifier.verify() - -Waits for the user to solve the reCAPTCHA and resolves with the reCAPTCHA token. - -Signature: - -```typescript -verify(): Promise; -``` -Returns: - -Promise<string> - -A Promise for the reCAPTCHA token. - diff --git a/docs-devsite/auth.samlauthprovider.md b/docs-devsite/auth.samlauthprovider.md deleted file mode 100644 index d25dd1999ed..00000000000 --- a/docs-devsite/auth.samlauthprovider.md +++ /dev/null @@ -1,119 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# SAMLAuthProvider class -An [AuthProvider](./auth.authprovider.md#authprovider_interface) for SAML. - -Signature: - -```typescript -export declare class SAMLAuthProvider extends FederatedAuthProvider -``` -Extends: FederatedAuthProvider - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(providerId)](./auth.samlauthprovider.md#samlauthproviderconstructor) | | Constructor. The providerId must start with "saml." | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [credentialFromError(error)](./auth.samlauthprovider.md#samlauthprovidercredentialfromerror) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. | -| [credentialFromJSON(json)](./auth.samlauthprovider.md#samlauthprovidercredentialfromjson) | static | Creates an [AuthCredential](./auth.authcredential.md#authcredential_class) from a JSON string or a plain object. | -| [credentialFromResult(userCredential)](./auth.samlauthprovider.md#samlauthprovidercredentialfromresult) | static | Generates an [AuthCredential](./auth.authcredential.md#authcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface) after a successful SAML flow completes. | - -## SAMLAuthProvider.(constructor) - -Constructor. The providerId must start with "saml." - -Signature: - -```typescript -constructor(providerId: string); -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| providerId | string | SAML provider ID. | - -## SAMLAuthProvider.credentialFromError() - -Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. - -Signature: - -```typescript -static credentialFromError(error: FirebaseError): AuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | | - -Returns: - -[AuthCredential](./auth.authcredential.md#authcredential_class) \| null - -## SAMLAuthProvider.credentialFromJSON() - -Creates an [AuthCredential](./auth.authcredential.md#authcredential_class) from a JSON string or a plain object. - -Signature: - -```typescript -static credentialFromJSON(json: string | object): AuthCredential; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| json | string \| object | A plain object or a JSON string | - -Returns: - -[AuthCredential](./auth.authcredential.md#authcredential_class) - -## SAMLAuthProvider.credentialFromResult() - -Generates an [AuthCredential](./auth.authcredential.md#authcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface) after a successful SAML flow completes. - -For example, to get an [AuthCredential](./auth.authcredential.md#authcredential_class), you could write the following code: - -```js -const userCredential = await signInWithPopup(auth, samlProvider); -const credential = SAMLAuthProvider.credentialFromResult(userCredential); - -``` - -Signature: - -```typescript -static credentialFromResult(userCredential: UserCredential): AuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | - -Returns: - -[AuthCredential](./auth.authcredential.md#authcredential_class) \| null - diff --git a/docs-devsite/auth.twitterauthprovider.md b/docs-devsite/auth.twitterauthprovider.md deleted file mode 100644 index 9ae64b6bdaf..00000000000 --- a/docs-devsite/auth.twitterauthprovider.md +++ /dev/null @@ -1,173 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# TwitterAuthProvider class -Provider for generating an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).TWITTER. - -Signature: - -```typescript -export declare class TwitterAuthProvider extends BaseOAuthProvider -``` -Extends: BaseOAuthProvider - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)()](./auth.twitterauthprovider.md#twitterauthproviderconstructor) | | Constructs a new instance of the TwitterAuthProvider class | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [PROVIDER\_ID](./auth.twitterauthprovider.md#twitterauthproviderprovider_id) | static | 'twitter.com' | Always set to [ProviderId](./auth.md#providerid).TWITTER. | -| [TWITTER\_SIGN\_IN\_METHOD](./auth.twitterauthprovider.md#twitterauthprovidertwitter_sign_in_method) | static | 'twitter.com' | Always set to [SignInMethod](./auth.md#signinmethod).TWITTER. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [credential(token, secret)](./auth.twitterauthprovider.md#twitterauthprovidercredential) | static | Creates a credential for Twitter. | -| [credentialFromError(error)](./auth.twitterauthprovider.md#twitterauthprovidercredentialfromerror) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. | -| [credentialFromResult(userCredential)](./auth.twitterauthprovider.md#twitterauthprovidercredentialfromresult) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). | - -## TwitterAuthProvider.(constructor) - -Constructs a new instance of the `TwitterAuthProvider` class - -Signature: - -```typescript -constructor(); -``` - -## TwitterAuthProvider.PROVIDER\_ID - -Always set to [ProviderId](./auth.md#providerid).TWITTER. - -Signature: - -```typescript -static readonly PROVIDER_ID: 'twitter.com'; -``` - -## TwitterAuthProvider.TWITTER\_SIGN\_IN\_METHOD - -Always set to [SignInMethod](./auth.md#signinmethod).TWITTER. - -Signature: - -```typescript -static readonly TWITTER_SIGN_IN_METHOD: 'twitter.com'; -``` - -## TwitterAuthProvider.credential() - -Creates a credential for Twitter. - -Signature: - -```typescript -static credential(token: string, secret: string): OAuthCredential; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| token | string | Twitter access token. | -| secret | string | Twitter secret. | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) - -## TwitterAuthProvider.credentialFromError() - -Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. - -Signature: - -```typescript -static credentialFromError(error: FirebaseError): OAuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null - -## TwitterAuthProvider.credentialFromResult() - -Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). - -Signature: - -```typescript -static credentialFromResult(userCredential: UserCredential): OAuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null - -### Example 1 - - -```javascript -// Sign in using a redirect. -const provider = new TwitterAuthProvider(); -// Start a sign in process for an unauthenticated user. -await signInWithRedirect(auth, provider); -// This will trigger a full page redirect away from your app - -// After returning from the redirect when your app initializes you can obtain the result -const result = await getRedirectResult(auth); -if (result) { - // This is the signed-in user - const user = result.user; - // This gives you a Twitter Access Token and Secret. - const credential = TwitterAuthProvider.credentialFromResult(result); - const token = credential.accessToken; - const secret = credential.secret; -} - -``` - -### Example 2 - - -```javascript -// Sign in using a popup. -const provider = new TwitterAuthProvider(); -const result = await signInWithPopup(auth, provider); - -// The signed-in user info. -const user = result.user; -// This gives you a Twitter Access Token and Secret. -const credential = TwitterAuthProvider.credentialFromResult(result); -const token = credential.accessToken; -const secret = credential.secret; - -``` - diff --git a/docs-devsite/auth.user.md b/docs-devsite/auth.user.md deleted file mode 100644 index 18a56a45901..00000000000 --- a/docs-devsite/auth.user.md +++ /dev/null @@ -1,204 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# User interface -A user account. - -Signature: - -```typescript -export interface User extends UserInfo -``` -Extends: [UserInfo](./auth.userinfo.md#userinfo_interface) - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [emailVerified](./auth.user.md#useremailverified) | boolean | Whether the email has been verified with [sendEmailVerification()](./auth.md#sendemailverification) and [applyActionCode()](./auth.md#applyactioncode). | -| [isAnonymous](./auth.user.md#userisanonymous) | boolean | Whether the user is authenticated using the [ProviderId](./auth.md#providerid).ANONYMOUS provider. | -| [metadata](./auth.user.md#usermetadata) | [UserMetadata](./auth.usermetadata.md#usermetadata_interface) | Additional metadata around user creation and sign-in times. | -| [providerData](./auth.user.md#userproviderdata) | [UserInfo](./auth.userinfo.md#userinfo_interface)\[\] | Additional per provider such as displayName and profile information. | -| [refreshToken](./auth.user.md#userrefreshtoken) | string | Refresh token used to reauthenticate the user. Avoid using this directly and prefer [User.getIdToken()](./auth.user.md#usergetidtoken) to refresh the ID token instead. | -| [tenantId](./auth.user.md#usertenantid) | string \| null | The user's tenant ID. | - -## Methods - -| Method | Description | -| --- | --- | -| [delete()](./auth.user.md#userdelete) | Deletes and signs out the user. | -| [getIdToken(forceRefresh)](./auth.user.md#usergetidtoken) | Returns a JSON Web Token (JWT) used to identify the user to a Firebase service. | -| [getIdTokenResult(forceRefresh)](./auth.user.md#usergetidtokenresult) | Returns a deserialized JSON Web Token (JWT) used to identitfy the user to a Firebase service. | -| [reload()](./auth.user.md#userreload) | Refreshes the user, if signed in. | -| [toJSON()](./auth.user.md#usertojson) | Returns a JSON-serializable representation of this object. | - -## User.emailVerified - -Whether the email has been verified with [sendEmailVerification()](./auth.md#sendemailverification) and [applyActionCode()](./auth.md#applyactioncode). - -Signature: - -```typescript -readonly emailVerified: boolean; -``` - -## User.isAnonymous - -Whether the user is authenticated using the [ProviderId](./auth.md#providerid).ANONYMOUS provider. - -Signature: - -```typescript -readonly isAnonymous: boolean; -``` - -## User.metadata - -Additional metadata around user creation and sign-in times. - -Signature: - -```typescript -readonly metadata: UserMetadata; -``` - -## User.providerData - -Additional per provider such as displayName and profile information. - -Signature: - -```typescript -readonly providerData: UserInfo[]; -``` - -## User.refreshToken - -Refresh token used to reauthenticate the user. Avoid using this directly and prefer [User.getIdToken()](./auth.user.md#usergetidtoken) to refresh the ID token instead. - -Signature: - -```typescript -readonly refreshToken: string; -``` - -## User.tenantId - -The user's tenant ID. - -This is a read-only property, which indicates the tenant ID used to sign in the user. This is null if the user is signed in from the parent project. - -Signature: - -```typescript -readonly tenantId: string | null; -``` - -### Example - - -```javascript -// Set the tenant ID on Auth instance. -auth.tenantId = 'TENANT_PROJECT_ID'; - -// All future sign-in request now include tenant ID. -const result = await signInWithEmailAndPassword(auth, email, password); -// result.user.tenantId should be 'TENANT_PROJECT_ID'. - -``` - -## User.delete() - -Deletes and signs out the user. - -Important: this is a security-sensitive operation that requires the user to have recently signed in. If this requirement isn't met, ask the user to authenticate again and then call one of the reauthentication methods like [reauthenticateWithCredential()](./auth.md#reauthenticatewithcredential). - -Signature: - -```typescript -delete(): Promise; -``` -Returns: - -Promise<void> - -## User.getIdToken() - -Returns a JSON Web Token (JWT) used to identify the user to a Firebase service. - -Returns the current token if it has not expired or if it will not expire in the next five minutes. Otherwise, this will refresh the token and return a new one. - -Signature: - -```typescript -getIdToken(forceRefresh?: boolean): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| forceRefresh | boolean | Force refresh regardless of token expiration. | - -Returns: - -Promise<string> - -## User.getIdTokenResult() - -Returns a deserialized JSON Web Token (JWT) used to identitfy the user to a Firebase service. - -Returns the current token if it has not expired or if it will not expire in the next five minutes. Otherwise, this will refresh the token and return a new one. - -Signature: - -```typescript -getIdTokenResult(forceRefresh?: boolean): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| forceRefresh | boolean | Force refresh regardless of token expiration. | - -Returns: - -Promise<[IdTokenResult](./auth.idtokenresult.md#idtokenresult_interface)> - -## User.reload() - -Refreshes the user, if signed in. - -Signature: - -```typescript -reload(): Promise; -``` -Returns: - -Promise<void> - -## User.toJSON() - -Returns a JSON-serializable representation of this object. - -Signature: - -```typescript -toJSON(): object; -``` -Returns: - -object - -A JSON-serializable representation of this object. - diff --git a/docs-devsite/auth.usercredential.md b/docs-devsite/auth.usercredential.md deleted file mode 100644 index 665a1ec253e..00000000000 --- a/docs-devsite/auth.usercredential.md +++ /dev/null @@ -1,59 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# UserCredential interface -A structure containing a [User](./auth.user.md#user_interface), the [OperationType](./auth.md#operationtype), and the provider ID. - -`operationType` could be [OperationType](./auth.md#operationtype).SIGN\_IN for a sign-in operation, [OperationType](./auth.md#operationtype).LINK for a linking operation and [OperationType](./auth.md#operationtype).REAUTHENTICATE for a reauthentication operation. - -Signature: - -```typescript -export interface UserCredential -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [operationType](./auth.usercredential.md#usercredentialoperationtype) | typeof [OperationTypeMap](./auth.md#operationtype)\[keyof typeof [OperationTypeMap](./auth.md#operationtype)\] | The type of operation which was used to authenticate the user (such as sign-in or link). | -| [providerId](./auth.usercredential.md#usercredentialproviderid) | string \| null | The provider which was used to authenticate the user. | -| [user](./auth.usercredential.md#usercredentialuser) | [User](./auth.user.md#user_interface) | The user authenticated by this credential. | - -## UserCredential.operationType - -The type of operation which was used to authenticate the user (such as sign-in or link). - -Signature: - -```typescript -operationType: typeof OperationTypeMap[keyof typeof OperationTypeMap]; -``` - -## UserCredential.providerId - -The provider which was used to authenticate the user. - -Signature: - -```typescript -providerId: string | null; -``` - -## UserCredential.user - -The user authenticated by this credential. - -Signature: - -```typescript -user: User; -``` diff --git a/docs-devsite/auth.userinfo.md b/docs-devsite/auth.userinfo.md deleted file mode 100644 index 7b49dc65f9c..00000000000 --- a/docs-devsite/auth.userinfo.md +++ /dev/null @@ -1,92 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# UserInfo interface -User profile information, visible only to the Firebase project's apps. - -Signature: - -```typescript -export interface UserInfo -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [displayName](./auth.userinfo.md#userinfodisplayname) | string \| null | The display name of the user. | -| [email](./auth.userinfo.md#userinfoemail) | string \| null | The email of the user. | -| [phoneNumber](./auth.userinfo.md#userinfophonenumber) | string \| null | The phone number normalized based on the E.164 standard (e.g. +16505550101) for the user. | -| [photoURL](./auth.userinfo.md#userinfophotourl) | string \| null | The profile photo URL of the user. | -| [providerId](./auth.userinfo.md#userinfoproviderid) | string | The provider used to authenticate the user. | -| [uid](./auth.userinfo.md#userinfouid) | string | The user's unique ID, scoped to the project. | - -## UserInfo.displayName - -The display name of the user. - -Signature: - -```typescript -readonly displayName: string | null; -``` - -## UserInfo.email - -The email of the user. - -Signature: - -```typescript -readonly email: string | null; -``` - -## UserInfo.phoneNumber - -The phone number normalized based on the E.164 standard (e.g. +16505550101) for the user. - -This is null if the user has no phone credential linked to the account. - -Signature: - -```typescript -readonly phoneNumber: string | null; -``` - -## UserInfo.photoURL - -The profile photo URL of the user. - -Signature: - -```typescript -readonly photoURL: string | null; -``` - -## UserInfo.providerId - -The provider used to authenticate the user. - -Signature: - -```typescript -readonly providerId: string; -``` - -## UserInfo.uid - -The user's unique ID, scoped to the project. - -Signature: - -```typescript -readonly uid: string; -``` diff --git a/docs-devsite/auth.usermetadata.md b/docs-devsite/auth.usermetadata.md deleted file mode 100644 index bb65b30eff5..00000000000 --- a/docs-devsite/auth.usermetadata.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# UserMetadata interface -Interface representing a user's metadata. - -Signature: - -```typescript -export interface UserMetadata -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [creationTime](./auth.usermetadata.md#usermetadatacreationtime) | string | Time the user was created. | -| [lastSignInTime](./auth.usermetadata.md#usermetadatalastsignintime) | string | Time the user last signed in. | - -## UserMetadata.creationTime - -Time the user was created. - -Signature: - -```typescript -readonly creationTime?: string; -``` - -## UserMetadata.lastSignInTime - -Time the user last signed in. - -Signature: - -```typescript -readonly lastSignInTime?: string; -``` diff --git a/docs-devsite/database.database.md b/docs-devsite/database.database.md deleted file mode 100644 index 62ce4f8a420..00000000000 --- a/docs-devsite/database.database.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Database class -Class representing a Firebase Realtime Database. - -Signature: - -```typescript -export declare class Database -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [app](./database.database.md#databaseapp) | | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this Realtime Database instance. | -| [type](./database.database.md#databasetype) | | (not declared) | Represents a Database instance. | - -## Database.app - -The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this Realtime Database instance. - -Signature: - -```typescript -readonly app: FirebaseApp; -``` - -## Database.type - -Represents a `Database` instance. - -Signature: - -```typescript -readonly 'type' = "database"; -``` diff --git a/docs-devsite/database.databasereference.md b/docs-devsite/database.databasereference.md deleted file mode 100644 index 13f19a3bf4f..00000000000 --- a/docs-devsite/database.databasereference.md +++ /dev/null @@ -1,68 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# DatabaseReference interface -A `DatabaseReference` represents a specific location in your Database and can be used for reading or writing data to that Database location. - -You can reference the root or child location in your Database by calling `ref()` or `ref("child/path")`. - -Writing is done with the `set()` method and reading can be done with the `on*()` method. See [https://firebase.google.com/docs/database/web/read-and-write](https://firebase.google.com/docs/database/web/read-and-write) - -Signature: - -```typescript -export declare interface DatabaseReference extends Query -``` -Extends: [Query](./database.query.md#query_interface) - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [key](./database.databasereference.md#databasereferencekey) | string \| null | The last part of the DatabaseReference's path.For example, "ada" is the key for https://<DATABASE_NAME>.firebaseio.com/users/ada.The key of a root DatabaseReference is null. | -| [parent](./database.databasereference.md#databasereferenceparent) | [DatabaseReference](./database.databasereference.md#databasereference_interface) \| null | The parent location of a DatabaseReference.The parent of a root DatabaseReference is null. | -| [root](./database.databasereference.md#databasereferenceroot) | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The root DatabaseReference of the Database. | - -## DatabaseReference.key - -The last part of the `DatabaseReference`'s path. - -For example, `"ada"` is the key for `https://.firebaseio.com/users/ada`. - -The key of a root `DatabaseReference` is `null`. - -Signature: - -```typescript -readonly key: string | null; -``` - -## DatabaseReference.parent - -The parent location of a `DatabaseReference`. - -The parent of a root `DatabaseReference` is `null`. - -Signature: - -```typescript -readonly parent: DatabaseReference | null; -``` - -## DatabaseReference.root - -The root `DatabaseReference` of the Database. - -Signature: - -```typescript -readonly root: DatabaseReference; -``` diff --git a/docs-devsite/database.datasnapshot.md b/docs-devsite/database.datasnapshot.md deleted file mode 100644 index 35e983def87..00000000000 --- a/docs-devsite/database.datasnapshot.md +++ /dev/null @@ -1,237 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# DataSnapshot class -A `DataSnapshot` contains data from a Database location. - -Any time you read data from the Database, you receive the data as a `DataSnapshot`. A `DataSnapshot` is passed to the event callbacks you attach with `on()` or `once()`. You can extract the contents of the snapshot as a JavaScript object by calling the `val()` method. Alternatively, you can traverse into the snapshot by calling `child()` to return child snapshots (which you could then call `val()` on). - -A `DataSnapshot` is an efficiently generated, immutable copy of the data at a Database location. It cannot be modified and will never change (to modify data, you always call the `set()` method on a `Reference` directly). - -Signature: - -```typescript -export declare class DataSnapshot -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [key](./database.datasnapshot.md#datasnapshotkey) | | string \| null | The key (last part of the path) of the location of this DataSnapshot.The last token in a Database location is considered its key. For example, "ada" is the key for the /users/ada/ node. Accessing the key on any DataSnapshot will return the key for the location that generated it. However, accessing the key on the root URL of a Database will return null. | -| [priority](./database.datasnapshot.md#datasnapshotpriority) | | string \| number \| null | Gets the priority value of the data in this DataSnapshot.Applications need not use priority but can order collections by ordinary properties (see [Sorting and filtering data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) ). | -| [ref](./database.datasnapshot.md#datasnapshotref) | | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location of this DataSnapshot. | -| [size](./database.datasnapshot.md#datasnapshotsize) | | number | Returns the number of child properties of this DataSnapshot. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [child(path)](./database.datasnapshot.md#datasnapshotchild) | | Gets another DataSnapshot for the location at the specified relative path.Passing a relative path to the child() method of a DataSnapshot returns another DataSnapshot for the location at the specified relative path. The relative path can either be a simple child name (for example, "ada") or a deeper, slash-separated path (for example, "ada/name/first"). If the child location has no data, an empty DataSnapshot (that is, a DataSnapshot whose value is null) is returned. | -| [exists()](./database.datasnapshot.md#datasnapshotexists) | | Returns true if this DataSnapshot contains any data. It is slightly more efficient than using snapshot.val() !== null. | -| [exportVal()](./database.datasnapshot.md#datasnapshotexportval) | | Exports the entire contents of the DataSnapshot as a JavaScript object.The exportVal() method is similar to val(), except priority information is included (if available), making it suitable for backing up your data. | -| [forEach(action)](./database.datasnapshot.md#datasnapshotforeach) | | Enumerates the top-level children in the DataSnapshot.Because of the way JavaScript objects work, the ordering of data in the JavaScript object returned by val() is not guaranteed to match the ordering on the server nor the ordering of onChildAdded() events. That is where forEach() comes in handy. It guarantees the children of a DataSnapshot will be iterated in their query order.If no explicit orderBy*() method is used, results are returned ordered by key (unless priorities are used, in which case, results are returned by priority). | -| [hasChild(path)](./database.datasnapshot.md#datasnapshothaschild) | | Returns true if the specified child path has (non-null) data. | -| [hasChildren()](./database.datasnapshot.md#datasnapshothaschildren) | | Returns whether or not the DataSnapshot has any non-null child properties.You can use hasChildren() to determine if a DataSnapshot has any children. If it does, you can enumerate them using forEach(). If it doesn't, then either this snapshot contains a primitive value (which can be retrieved with val()) or it is empty (in which case, val() will return null). | -| [toJSON()](./database.datasnapshot.md#datasnapshottojson) | | Returns a JSON-serializable representation of this object. | -| [val()](./database.datasnapshot.md#datasnapshotval) | | Extracts a JavaScript value from a DataSnapshot.Depending on the data in a DataSnapshot, the val() method may return a scalar type (string, number, or boolean), an array, or an object. It may also return null, indicating that the DataSnapshot is empty (contains no data). | - -## DataSnapshot.key - -The key (last part of the path) of the location of this `DataSnapshot`. - -The last token in a Database location is considered its key. For example, "ada" is the key for the /users/ada/ node. Accessing the key on any `DataSnapshot` will return the key for the location that generated it. However, accessing the key on the root URL of a Database will return `null`. - -Signature: - -```typescript -get key(): string | null; -``` - -## DataSnapshot.priority - -Gets the priority value of the data in this `DataSnapshot`. - -Applications need not use priority but can order collections by ordinary properties (see [Sorting and filtering data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) ). - -Signature: - -```typescript -get priority(): string | number | null; -``` - -## DataSnapshot.ref - -The location of this DataSnapshot. - -Signature: - -```typescript -readonly ref: DatabaseReference; -``` - -## DataSnapshot.size - -Returns the number of child properties of this `DataSnapshot`. - -Signature: - -```typescript -get size(): number; -``` - -## DataSnapshot.child() - -Gets another `DataSnapshot` for the location at the specified relative path. - -Passing a relative path to the `child()` method of a DataSnapshot returns another `DataSnapshot` for the location at the specified relative path. The relative path can either be a simple child name (for example, "ada") or a deeper, slash-separated path (for example, "ada/name/first"). If the child location has no data, an empty `DataSnapshot` (that is, a `DataSnapshot` whose value is `null`) is returned. - -Signature: - -```typescript -child(path: string): DataSnapshot; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| path | string | A relative path to the location of child data. | - -Returns: - -[DataSnapshot](./database.datasnapshot.md#datasnapshot_class) - -## DataSnapshot.exists() - -Returns true if this `DataSnapshot` contains any data. It is slightly more efficient than using `snapshot.val() !== null`. - -Signature: - -```typescript -exists(): boolean; -``` -Returns: - -boolean - -## DataSnapshot.exportVal() - -Exports the entire contents of the DataSnapshot as a JavaScript object. - -The `exportVal()` method is similar to `val()`, except priority information is included (if available), making it suitable for backing up your data. - -Signature: - -```typescript -exportVal(): any; -``` -Returns: - -any - -The DataSnapshot's contents as a JavaScript value (Object, Array, string, number, boolean, or `null`). - -## DataSnapshot.forEach() - -Enumerates the top-level children in the `DataSnapshot`. - -Because of the way JavaScript objects work, the ordering of data in the JavaScript object returned by `val()` is not guaranteed to match the ordering on the server nor the ordering of `onChildAdded()` events. That is where `forEach()` comes in handy. It guarantees the children of a `DataSnapshot` will be iterated in their query order. - -If no explicit `orderBy*()` method is used, results are returned ordered by key (unless priorities are used, in which case, results are returned by priority). - -Signature: - -```typescript -forEach(action: (child: DataSnapshot) => boolean | void): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| action | (child: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => boolean \| void | A function that will be called for each child DataSnapshot. The callback can return true to cancel further enumeration. | - -Returns: - -boolean - -true if enumeration was canceled due to your callback returning true. - -## DataSnapshot.hasChild() - -Returns true if the specified child path has (non-null) data. - -Signature: - -```typescript -hasChild(path: string): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| path | string | A relative path to the location of a potential child. | - -Returns: - -boolean - -`true` if data exists at the specified child path; else `false`. - -## DataSnapshot.hasChildren() - -Returns whether or not the `DataSnapshot` has any non-`null` child properties. - -You can use `hasChildren()` to determine if a `DataSnapshot` has any children. If it does, you can enumerate them using `forEach()`. If it doesn't, then either this snapshot contains a primitive value (which can be retrieved with `val()`) or it is empty (in which case, `val()` will return `null`). - -Signature: - -```typescript -hasChildren(): boolean; -``` -Returns: - -boolean - -true if this snapshot has any children; else false. - -## DataSnapshot.toJSON() - -Returns a JSON-serializable representation of this object. - -Signature: - -```typescript -toJSON(): object | null; -``` -Returns: - -object \| null - -## DataSnapshot.val() - -Extracts a JavaScript value from a `DataSnapshot`. - -Depending on the data in a `DataSnapshot`, the `val()` method may return a scalar type (string, number, or boolean), an array, or an object. It may also return null, indicating that the `DataSnapshot` is empty (contains no data). - -Signature: - -```typescript -val(): any; -``` -Returns: - -any - -The DataSnapshot's contents as a JavaScript value (Object, Array, string, number, boolean, or `null`). - diff --git a/docs-devsite/database.listenoptions.md b/docs-devsite/database.listenoptions.md deleted file mode 100644 index 171067dd020..00000000000 --- a/docs-devsite/database.listenoptions.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ListenOptions interface -An options objects that can be used to customize a listener. - -Signature: - -```typescript -export declare interface ListenOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [onlyOnce](./database.listenoptions.md#listenoptionsonlyonce) | boolean | Whether to remove the listener after its first invocation. | - -## ListenOptions.onlyOnce - -Whether to remove the listener after its first invocation. - -Signature: - -```typescript -readonly onlyOnce?: boolean; -``` diff --git a/docs-devsite/database.md b/docs-devsite/database.md deleted file mode 100644 index 114c364858a..00000000000 --- a/docs-devsite/database.md +++ /dev/null @@ -1,1393 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# database package -Firebase Realtime Database - -## Functions - -| Function | Description | -| --- | --- | -| [child(parent, path)](./database.md#child) | Gets a Reference for the location at the specified relative path.The relative path can either be a simple child name (for example, "ada") or a deeper slash-separated path (for example, "ada/name/first"). | -| [connectDatabaseEmulator(db, host, port, options)](./database.md#connectdatabaseemulator) | Modify the provided instance to communicate with the Realtime Database emulator.

Note: This method must be called before performing any other operation. | -| [enableLogging(enabled, persistent)](./database.md#enablelogging) | Logs debugging information to the console. | -| [enableLogging(logger)](./database.md#enablelogging) | Logs debugging information to the console. | -| [endAt(value, key)](./database.md#endat) | Creates a QueryConstraint with the specified ending point.Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The ending point is inclusive, so children with exactly the specified value will be included in the query. The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have a key name less than or equal to the specified key.You can read more about endAt() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | -| [endBefore(value, key)](./database.md#endbefore) | Creates a QueryConstraint with the specified ending point (exclusive).Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The ending point is exclusive. If only a value is provided, children with a value less than the specified value will be included in the query. If a key is specified, then children must have a value less than or equal to the specified value and a key name less than the specified key. | -| [equalTo(value, key)](./database.md#equalto) | Creates a QueryConstraint that includes children that match the specified value.Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have exactly the specified key as their key name. This can be used to filter result sets with many matches for the same value.You can read more about equalTo() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | -| [forceLongPolling()](./database.md#forcelongpolling) | Force the use of longPolling instead of websockets. This will be ignored if websocket protocol is used in databaseURL. | -| [forceWebSockets()](./database.md#forcewebsockets) | Force the use of websockets instead of longPolling. | -| [get(query)](./database.md#get) | Gets the most up-to-date result for this query. | -| [getDatabase(app, url)](./database.md#getdatabase) | Returns the instance of the Realtime Database SDK that is associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). Initializes a new instance with with default settings if no instance exists or if the existing instance uses a custom database URL. | -| [goOffline(db)](./database.md#gooffline) | Disconnects from the server (all Database operations will be completed offline).The client automatically maintains a persistent connection to the Database server, which will remain active indefinitely and reconnect when disconnected. However, the goOffline() and goOnline() methods may be used to control the client connection in cases where a persistent connection is undesirable.While offline, the client will no longer receive data updates from the Database. However, all Database operations performed locally will continue to immediately fire events, allowing your application to continue behaving normally. Additionally, each operation performed locally will automatically be queued and retried upon reconnection to the Database server.To reconnect to the Database and begin receiving remote events, see goOnline(). | -| [goOnline(db)](./database.md#goonline) | Reconnects to the server and synchronizes the offline Database state with the server state.This method should be used after disabling the active connection with goOffline(). Once reconnected, the client will transmit the proper data and fire the appropriate events so that your client "catches up" automatically. | -| [increment(delta)](./database.md#increment) | Returns a placeholder value that can be used to atomically increment the current database value by the provided delta. | -| [limitToFirst(limit)](./database.md#limittofirst) | Creates a new QueryConstraint that if limited to the first specific number of children.The limitToFirst() method is used to set a maximum number of children to be synced for a given callback. If we set a limit of 100, we will initially only receive up to 100 child_added events. If we have fewer than 100 messages stored in our Database, a child_added event will fire for each message. However, if we have over 100 messages, we will only receive a child_added event for the first 100 ordered messages. As items change, we will receive child_removed events for each item that drops out of the active list so that the total number stays at 100.You can read more about limitToFirst() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | -| [limitToLast(limit)](./database.md#limittolast) | Creates a new QueryConstraint that is limited to return only the last specified number of children.The limitToLast() method is used to set a maximum number of children to be synced for a given callback. If we set a limit of 100, we will initially only receive up to 100 child_added events. If we have fewer than 100 messages stored in our Database, a child_added event will fire for each message. However, if we have over 100 messages, we will only receive a child_added event for the last 100 ordered messages. As items change, we will receive child_removed events for each item that drops out of the active list so that the total number stays at 100.You can read more about limitToLast() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | -| [off(query, eventType, callback)](./database.md#off) | Detaches a callback previously attached with the corresponding on*() (onValue, onChildAdded) listener. Note: This is not the recommended way to remove a listener. Instead, please use the returned callback function from the respective on* callbacks.Detach a callback previously attached with on*(). Calling off() on a parent listener will not automatically remove listeners registered on child nodes, off() must also be called on any child listeners to remove the callback.If a callback is not specified, all callbacks for the specified eventType will be removed. Similarly, if no eventType is specified, all callbacks for the Reference will be removed.Individual listeners can also be removed by invoking their unsubscribe callbacks. | -| [onChildAdded(query, callback, cancelCallback)](./database.md#onchildadded) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildAdded event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The DataSnapshot passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | -| [onChildAdded(query, callback, options)](./database.md#onchildadded) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildAdded event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The DataSnapshot passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | -| [onChildAdded(query, callback, cancelCallback, options)](./database.md#onchildadded) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildAdded event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The DataSnapshot passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | -| [onChildChanged(query, callback, cancelCallback)](./database.md#onchildchanged) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildChanged event will be triggered when the data stored in a child (or any of its descendants) changes. Note that a single child_changed event may represent multiple changes to the child. The DataSnapshot passed to the callback will contain the new child contents. For ordering purposes, the callback is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | -| [onChildChanged(query, callback, options)](./database.md#onchildchanged) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildChanged event will be triggered when the data stored in a child (or any of its descendants) changes. Note that a single child_changed event may represent multiple changes to the child. The DataSnapshot passed to the callback will contain the new child contents. For ordering purposes, the callback is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | -| [onChildChanged(query, callback, cancelCallback, options)](./database.md#onchildchanged) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildChanged event will be triggered when the data stored in a child (or any of its descendants) changes. Note that a single child_changed event may represent multiple changes to the child. The DataSnapshot passed to the callback will contain the new child contents. For ordering purposes, the callback is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | -| [onChildMoved(query, callback, cancelCallback)](./database.md#onchildmoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildMoved event will be triggered when a child's sort order changes such that its position relative to its siblings changes. The DataSnapshot passed to the callback will be for the data of the child that has moved. It is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | -| [onChildMoved(query, callback, options)](./database.md#onchildmoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildMoved event will be triggered when a child's sort order changes such that its position relative to its siblings changes. The DataSnapshot passed to the callback will be for the data of the child that has moved. It is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | -| [onChildMoved(query, callback, cancelCallback, options)](./database.md#onchildmoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildMoved event will be triggered when a child's sort order changes such that its position relative to its siblings changes. The DataSnapshot passed to the callback will be for the data of the child that has moved. It is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | -| [onChildRemoved(query, callback, cancelCallback)](./database.md#onchildremoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildRemoved event will be triggered once every time a child is removed. The DataSnapshot passed into the callback will be the old data for the child that was removed. A child will get removed when either:- a client explicitly calls remove() on that child or one of its ancestors - a client calls set(null) on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) | -| [onChildRemoved(query, callback, options)](./database.md#onchildremoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildRemoved event will be triggered once every time a child is removed. The DataSnapshot passed into the callback will be the old data for the child that was removed. A child will get removed when either:- a client explicitly calls remove() on that child or one of its ancestors - a client calls set(null) on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) | -| [onChildRemoved(query, callback, cancelCallback, options)](./database.md#onchildremoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildRemoved event will be triggered once every time a child is removed. The DataSnapshot passed into the callback will be the old data for the child that was removed. A child will get removed when either:- a client explicitly calls remove() on that child or one of its ancestors - a client calls set(null) on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) | -| [onDisconnect(ref)](./database.md#ondisconnect) | Returns an OnDisconnect object - see [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information on how to use it. | -| [onValue(query, callback, cancelCallback)](./database.md#onvalue) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onValue event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The DataSnapshot passed to the callback will be for the location at which on() was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty DataSnapshot (val() will return null). | -| [onValue(query, callback, options)](./database.md#onvalue) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onValue event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The DataSnapshot passed to the callback will be for the location at which on() was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty DataSnapshot (val() will return null). | -| [onValue(query, callback, cancelCallback, options)](./database.md#onvalue) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onValue event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The DataSnapshot passed to the callback will be for the location at which on() was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty DataSnapshot (val() will return null). | -| [orderByChild(path)](./database.md#orderbychild) | Creates a new QueryConstraint that orders by the specified child key.Queries can only order by one key at a time. Calling orderByChild() multiple times on the same query is an error.Firebase queries allow you to order your data by any child key on the fly. However, if you know in advance what your indexes will be, you can define them via the .indexOn rule in your Security Rules for better performance. See the[https://firebase.google.com/docs/database/security/indexing-data](https://firebase.google.com/docs/database/security/indexing-data) rule for more information.You can read more about orderByChild() in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). | -| [orderByKey()](./database.md#orderbykey) | Creates a new QueryConstraint that orders by the key.Sorts the results of a query by their (ascending) key values.You can read more about orderByKey() in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). | -| [orderByPriority()](./database.md#orderbypriority) | Creates a new QueryConstraint that orders by priority.Applications need not use priority but can order collections by ordinary properties (see [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data) for alternatives to priority. | -| [orderByValue()](./database.md#orderbyvalue) | Creates a new QueryConstraint that orders by value.If the children of a query are all scalar values (string, number, or boolean), you can order the results by their (ascending) values.You can read more about orderByValue() in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). | -| [push(parent, value)](./database.md#push) | Generates a new child location using a unique key and returns its Reference.This is the most common pattern for adding data to a collection of items.If you provide a value to push(), the value is written to the generated location. If you don't pass a value, nothing is written to the database and the child remains empty (but you can use the Reference elsewhere).The unique keys generated by push() are ordered by the current time, so the resulting list of items is chronologically sorted. The keys are also designed to be unguessable (they contain 72 random bits of entropy).See [Append to a list of data](https://firebase.google.com/docs/database/web/lists-of-data#append_to_a_list_of_data). See [The 2^120 Ways to Ensure Unique Identifiers](https://firebase.googleblog.com/2015/02/the-2120-ways-to-ensure-unique_68.html). | -| [query(query, queryConstraints)](./database.md#query) | Creates a new immutable instance of Query that is extended to also include additional query constraints. | -| [ref(db, path)](./database.md#ref) | Returns a Reference representing the location in the Database corresponding to the provided path. If no path is provided, the Reference will point to the root of the Database. | -| [refFromURL(db, url)](./database.md#reffromurl) | Returns a Reference representing the location in the Database corresponding to the provided Firebase URL.An exception is thrown if the URL is not a valid Firebase Database URL or it has a different domain than the current Database instance.Note that all query parameters (orderBy, limitToLast, etc.) are ignored and are not applied to the returned Reference. | -| [remove(ref)](./database.md#remove) | Removes the data at this Database location.Any data at child locations will also be deleted.The effect of the remove will be visible immediately and the corresponding event 'value' will be triggered. Synchronization of the remove to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the onComplete callback will be called asynchronously after synchronization has finished. | -| [runTransaction(ref, transactionUpdate, options)](./database.md#runtransaction) | Atomically modifies the data at this location.Atomically modify the data at this location. Unlike a normal set(), which just overwrites the data regardless of its previous value, runTransaction() is used to modify the existing value to a new value, ensuring there are no conflicts with other clients writing to the same location at the same time.To accomplish this, you pass runTransaction() an update function which is used to transform the current value into a new value. If another client writes to the location before your new value is successfully written, your update function will be called again with the new current value, and the write will be retried. This will happen repeatedly until your write succeeds without conflict or you abort the transaction by not returning a value from your update function.Note: Modifying data with set() will cancel any pending transactions at that location, so extreme care should be taken if mixing set() and runTransaction() to update the same data.Note: When using transactions with Security and Firebase Rules in place, be aware that a client needs .read access in addition to .write access in order to perform a transaction. This is because the client-side nature of transactions requires the client to read the data in order to transactionally update it. | -| [serverTimestamp()](./database.md#servertimestamp) | Returns a placeholder value for auto-populating the current timestamp (time since the Unix epoch, in milliseconds) as determined by the Firebase servers. | -| [set(ref, value)](./database.md#set) | Writes data to this Database location.This will overwrite any data at this location and all child locations.The effect of the write will be visible immediately, and the corresponding events ("value", "child\_added", etc.) will be triggered. Synchronization of the data to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the onComplete callback will be called asynchronously after synchronization has finished.Passing null for the new value is equivalent to calling remove(); namely, all data at this location and all child locations will be deleted.set() will remove any priority stored at this location, so if priority is meant to be preserved, you need to use setWithPriority() instead.Note that modifying data with set() will cancel any pending transactions at that location, so extreme care should be taken if mixing set() and transaction() to modify the same data.A single set() will generate a single "value" event at the location where the set() was performed. | -| [setPriority(ref, priority)](./database.md#setpriority) | Sets a priority for the data at this Database location.Applications need not use priority but can order collections by ordinary properties (see [Sorting and filtering data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) ). | -| [setWithPriority(ref, value, priority)](./database.md#setwithpriority) | Writes data the Database location. Like set() but also specifies the priority for that data.Applications need not use priority but can order collections by ordinary properties (see [Sorting and filtering data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) ). | -| [startAfter(value, key)](./database.md#startafter) | Creates a QueryConstraint with the specified starting point (exclusive).Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The starting point is exclusive. If only a value is provided, children with a value greater than the specified value will be included in the query. If a key is specified, then children must have a value greater than or equal to the specified value and a a key name greater than the specified key. | -| [startAt(value, key)](./database.md#startat) | Creates a QueryConstraint with the specified starting point.Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The starting point is inclusive, so children with exactly the specified value will be included in the query. The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have a key name greater than or equal to the specified key.You can read more about startAt() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | -| [update(ref, values)](./database.md#update) | Writes multiple values to the Database at once.The values argument contains multiple property-value pairs that will be written to the Database together. Each child property can either be a simple property (for example, "name") or a relative path (for example, "name/first") from the current location to the data to update.As opposed to the set() method, update() can be use to selectively update only the referenced properties at the current location (instead of replacing all the child properties at the current location).The effect of the write will be visible immediately, and the corresponding events ('value', 'child\_added', etc.) will be triggered. Synchronization of the data to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the onComplete callback will be called asynchronously after synchronization has finished.A single update() will generate a single "value" event at the location where the update() was performed, regardless of how many children were modified.Note that modifying data with update() will cancel any pending transactions at that location, so extreme care should be taken if mixing update() and transaction() to modify the same data.Passing null to update() will remove the data at this location.See [Introducing multi-location updates and more](https://firebase.googleblog.com/2015/09/introducing-multi-location-updates-and_86.html). | - -## Classes - -| Class | Description | -| --- | --- | -| [Database](./database.database.md#database_class) | Class representing a Firebase Realtime Database. | -| [DataSnapshot](./database.datasnapshot.md#datasnapshot_class) | A DataSnapshot contains data from a Database location.Any time you read data from the Database, you receive the data as a DataSnapshot. A DataSnapshot is passed to the event callbacks you attach with on() or once(). You can extract the contents of the snapshot as a JavaScript object by calling the val() method. Alternatively, you can traverse into the snapshot by calling child() to return child snapshots (which you could then call val() on).A DataSnapshot is an efficiently generated, immutable copy of the data at a Database location. It cannot be modified and will never change (to modify data, you always call the set() method on a Reference directly). | -| [OnDisconnect](./database.ondisconnect.md#ondisconnect_class) | The onDisconnect class allows you to write or clear data when your client disconnects from the Database server. These updates occur whether your client disconnects cleanly or not, so you can rely on them to clean up data even if a connection is dropped or a client crashes.The onDisconnect class is most commonly used to manage presence in applications where it is useful to detect how many clients are connected and when other clients disconnect. See [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information.To avoid problems when a connection is dropped before the requests can be transferred to the Database server, these functions should be called before writing any data.Note that onDisconnect operations are only triggered once. If you want an operation to occur each time a disconnect occurs, you'll need to re-establish the onDisconnect operations each time you reconnect. | -| [QueryConstraint](./database.queryconstraint.md#queryconstraint_class) | A QueryConstraint is used to narrow the set of documents returned by a Database query. QueryConstraints are created by invoking [endAt()](./database.md#endat), [endBefore()](./database.md#endbefore), [startAt()](./database.md#startat), [startAfter()](./database.md#startafter), [limitToFirst()](./database.md#limittofirst), [limitToLast()](./database.md#limittolast), [orderByChild()](./database.md#orderbychild), [orderByChild()](./database.md#orderbychild), [orderByKey()](./database.md#orderbykey) , [orderByPriority()](./database.md#orderbypriority) , [orderByValue()](./database.md#orderbyvalue) or [equalTo()](./database.md#equalto) and can then be passed to [query()](./database.md#query) to create a new query instance that also contains this QueryConstraint. | -| [TransactionResult](./database.transactionresult.md#transactionresult_class) | A type for the resolve value of [runTransaction()](./database.md#runtransaction). | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [DatabaseReference](./database.databasereference.md#databasereference_interface) | A DatabaseReference represents a specific location in your Database and can be used for reading or writing data to that Database location.You can reference the root or child location in your Database by calling ref() or ref("child/path").Writing is done with the set() method and reading can be done with the on*() method. See [https://firebase.google.com/docs/database/web/read-and-write](https://firebase.google.com/docs/database/web/read-and-write) | -| [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An options objects that can be used to customize a listener. | -| [Query](./database.query.md#query_interface) | A Query sorts and filters the data at a Database location so only a subset of the child data is included. This can be used to order a collection of data by some attribute (for example, height of dinosaurs) as well as to restrict a large list of items (for example, chat messages) down to a number suitable for synchronizing to the client. Queries are created by chaining together one or more of the filter methods defined here.Just as with a DatabaseReference, you can receive data from a Query by using the on*() methods. You will only receive events and DataSnapshots for the subset of the data that matches your query.See [https://firebase.google.com/docs/database/web/lists-of-data\#sorting\_and\_filtering\_data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) for more information. | -| [ThenableReference](./database.thenablereference.md#thenablereference_interface) | A Promise that can also act as a DatabaseReference when returned by [push()](./database.md#push). The reference is available immediately and the Promise resolves as the write to the backend completes. | -| [TransactionOptions](./database.transactionoptions.md#transactionoptions_interface) | An options object to configure transactions. | - -## Type Aliases - -| Type Alias | Description | -| --- | --- | -| [EventType](./database.md#eventtype) | One of the following strings: "value", "child\_added", "child\_changed", "child\_removed", or "child\_moved." | -| [QueryConstraintType](./database.md#queryconstrainttype) | Describes the different query constraints available in this SDK. | -| [Unsubscribe](./database.md#unsubscribe) | A callback that can invoked to remove a listener. | - -## child() - -Gets a `Reference` for the location at the specified relative path. - -The relative path can either be a simple child name (for example, "ada") or a deeper slash-separated path (for example, "ada/name/first"). - -Signature: - -```typescript -export declare function child(parent: DatabaseReference, path: string): DatabaseReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| parent | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The parent location. | -| path | string | A relative path from this location to the desired child location. | - -Returns: - -[DatabaseReference](./database.databasereference.md#databasereference_interface) - -The specified child location. - -## connectDatabaseEmulator() - -Modify the provided instance to communicate with the Realtime Database emulator. - -

Note: This method must be called before performing any other operation. - -Signature: - -```typescript -export declare function connectDatabaseEmulator(db: Database, host: string, port: number, options?: { - mockUserToken?: EmulatorMockTokenOptions | string; -}): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| db | [Database](./database.database.md#database_class) | The instance to modify. | -| host | string | The emulator host (ex: localhost) | -| port | number | The emulator port (ex: 8080) | -| options | { mockUserToken?: [EmulatorMockTokenOptions](./util.md#emulatormocktokenoptions) \| string; } | | - -Returns: - -void - -## enableLogging() - -Logs debugging information to the console. - -Signature: - -```typescript -export declare function enableLogging(enabled: boolean, persistent?: boolean): any; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| enabled | boolean | Enables logging if true, disables logging if false. | -| persistent | boolean | Remembers the logging state between page refreshes if true. | - -Returns: - -any - -## enableLogging() - -Logs debugging information to the console. - -Signature: - -```typescript -export declare function enableLogging(logger: (message: string) => unknown): any; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| logger | (message: string) => unknown | A custom logger function to control how things get logged. | - -Returns: - -any - -## endAt() - -Creates a `QueryConstraint` with the specified ending point. - -Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. - -The ending point is inclusive, so children with exactly the specified value will be included in the query. The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have a key name less than or equal to the specified key. - -You can read more about `endAt()` in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). - -Signature: - -```typescript -export declare function endAt(value: number | string | boolean | null, key?: string): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| value | number \| string \| boolean \| null | The value to end at. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | -| key | string | The child key to end at, among the children with the previously specified priority. This argument is only allowed if ordering by child, value, or priority. | - -Returns: - -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) - -## endBefore() - -Creates a `QueryConstraint` with the specified ending point (exclusive). - -Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. - -The ending point is exclusive. If only a value is provided, children with a value less than the specified value will be included in the query. If a key is specified, then children must have a value less than or equal to the specified value and a key name less than the specified key. - -Signature: - -```typescript -export declare function endBefore(value: number | string | boolean | null, key?: string): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| value | number \| string \| boolean \| null | The value to end before. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | -| key | string | The child key to end before, among the children with the previously specified priority. This argument is only allowed if ordering by child, value, or priority. | - -Returns: - -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) - -## equalTo() - -Creates a `QueryConstraint` that includes children that match the specified value. - -Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. - -The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have exactly the specified key as their key name. This can be used to filter result sets with many matches for the same value. - -You can read more about `equalTo()` in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). - -Signature: - -```typescript -export declare function equalTo(value: number | string | boolean | null, key?: string): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| value | number \| string \| boolean \| null | The value to match for. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | -| key | string | The child key to start at, among the children with the previously specified priority. This argument is only allowed if ordering by child, value, or priority. | - -Returns: - -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) - -## forceLongPolling() - -Force the use of longPolling instead of websockets. This will be ignored if websocket protocol is used in databaseURL. - -Signature: - -```typescript -export declare function forceLongPolling(): void; -``` -Returns: - -void - -## forceWebSockets() - -Force the use of websockets instead of longPolling. - -Signature: - -```typescript -export declare function forceWebSockets(): void; -``` -Returns: - -void - -## get() - -Gets the most up-to-date result for this query. - -Signature: - -```typescript -export declare function get(query: Query): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | - -Returns: - -Promise<[DataSnapshot](./database.datasnapshot.md#datasnapshot_class)> - -A `Promise` which resolves to the resulting DataSnapshot if a value is available, or rejects if the client is unable to return a value (e.g., if the server is unreachable and there is nothing cached). - -## getDatabase() - -Returns the instance of the Realtime Database SDK that is associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). Initializes a new instance with with default settings if no instance exists or if the existing instance uses a custom database URL. - -Signature: - -```typescript -export declare function getDatabase(app?: FirebaseApp, url?: string): Database; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance that the returned Realtime Database instance is associated with. | -| url | string | The URL of the Realtime Database instance to connect to. If not provided, the SDK connects to the default instance of the Firebase App. | - -Returns: - -[Database](./database.database.md#database_class) - -The `Database` instance of the provided app. - -## goOffline() - -Disconnects from the server (all Database operations will be completed offline). - -The client automatically maintains a persistent connection to the Database server, which will remain active indefinitely and reconnect when disconnected. However, the `goOffline()` and `goOnline()` methods may be used to control the client connection in cases where a persistent connection is undesirable. - -While offline, the client will no longer receive data updates from the Database. However, all Database operations performed locally will continue to immediately fire events, allowing your application to continue behaving normally. Additionally, each operation performed locally will automatically be queued and retried upon reconnection to the Database server. - -To reconnect to the Database and begin receiving remote events, see `goOnline()`. - -Signature: - -```typescript -export declare function goOffline(db: Database): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| db | [Database](./database.database.md#database_class) | The instance to disconnect. | - -Returns: - -void - -## goOnline() - -Reconnects to the server and synchronizes the offline Database state with the server state. - -This method should be used after disabling the active connection with `goOffline()`. Once reconnected, the client will transmit the proper data and fire the appropriate events so that your client "catches up" automatically. - -Signature: - -```typescript -export declare function goOnline(db: Database): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| db | [Database](./database.database.md#database_class) | The instance to reconnect. | - -Returns: - -void - -## increment() - -Returns a placeholder value that can be used to atomically increment the current database value by the provided delta. - -Signature: - -```typescript -export declare function increment(delta: number): object; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| delta | number | the amount to modify the current value atomically. | - -Returns: - -object - -A placeholder value for modifying data atomically server-side. - -## limitToFirst() - -Creates a new `QueryConstraint` that if limited to the first specific number of children. - -The `limitToFirst()` method is used to set a maximum number of children to be synced for a given callback. If we set a limit of 100, we will initially only receive up to 100 `child_added` events. If we have fewer than 100 messages stored in our Database, a `child_added` event will fire for each message. However, if we have over 100 messages, we will only receive a `child_added` event for the first 100 ordered messages. As items change, we will receive `child_removed` events for each item that drops out of the active list so that the total number stays at 100. - -You can read more about `limitToFirst()` in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). - -Signature: - -```typescript -export declare function limitToFirst(limit: number): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| limit | number | The maximum number of nodes to include in this query. | - -Returns: - -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) - -## limitToLast() - -Creates a new `QueryConstraint` that is limited to return only the last specified number of children. - -The `limitToLast()` method is used to set a maximum number of children to be synced for a given callback. If we set a limit of 100, we will initially only receive up to 100 `child_added` events. If we have fewer than 100 messages stored in our Database, a `child_added` event will fire for each message. However, if we have over 100 messages, we will only receive a `child_added` event for the last 100 ordered messages. As items change, we will receive `child_removed` events for each item that drops out of the active list so that the total number stays at 100. - -You can read more about `limitToLast()` in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). - -Signature: - -```typescript -export declare function limitToLast(limit: number): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| limit | number | The maximum number of nodes to include in this query. | - -Returns: - -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) - -## off() - -Detaches a callback previously attached with the corresponding `on*()` (`onValue`, `onChildAdded`) listener. Note: This is not the recommended way to remove a listener. Instead, please use the returned callback function from the respective `on*` callbacks. - -Detach a callback previously attached with `on*()`. Calling `off()` on a parent listener will not automatically remove listeners registered on child nodes, `off()` must also be called on any child listeners to remove the callback. - -If a callback is not specified, all callbacks for the specified eventType will be removed. Similarly, if no eventType is specified, all callbacks for the `Reference` will be removed. - -Individual listeners can also be removed by invoking their unsubscribe callbacks. - -Signature: - -```typescript -export declare function off(query: Query, eventType?: EventType, callback?: (snapshot: DataSnapshot, previousChildName?: string | null) => unknown): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query that the listener was registered with. | -| eventType | [EventType](./database.md#eventtype) | One of the following strings: "value", "child\_added", "child\_changed", "child\_removed", or "child\_moved." If omitted, all callbacks for the Reference will be removed. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName?: string \| null) => unknown | The callback function that was passed to on() or undefined to remove all callbacks. | - -Returns: - -void - -## onChildAdded() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onChildAdded` event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The `DataSnapshot` passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. - -Signature: - -```typescript -export declare function onChildAdded(query: Query, callback: (snapshot: DataSnapshot, previousChildName?: string | null) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName?: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | -| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onChildAdded() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onChildAdded` event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The `DataSnapshot` passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. - -Signature: - -```typescript -export declare function onChildAdded(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, options: ListenOptions): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | -| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onChildAdded() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onChildAdded` event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The `DataSnapshot` passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. - -Signature: - -```typescript -export declare function onChildAdded(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | -| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | -| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onChildChanged() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onChildChanged` event will be triggered when the data stored in a child (or any of its descendants) changes. Note that a single `child_changed` event may represent multiple changes to the child. The `DataSnapshot` passed to the callback will contain the new child contents. For ordering purposes, the callback is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. - -Signature: - -```typescript -export declare function onChildChanged(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | -| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onChildChanged() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onChildChanged` event will be triggered when the data stored in a child (or any of its descendants) changes. Note that a single `child_changed` event may represent multiple changes to the child. The `DataSnapshot` passed to the callback will contain the new child contents. For ordering purposes, the callback is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. - -Signature: - -```typescript -export declare function onChildChanged(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, options: ListenOptions): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | -| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onChildChanged() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onChildChanged` event will be triggered when the data stored in a child (or any of its descendants) changes. Note that a single `child_changed` event may represent multiple changes to the child. The `DataSnapshot` passed to the callback will contain the new child contents. For ordering purposes, the callback is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. - -Signature: - -```typescript -export declare function onChildChanged(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | -| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | -| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onChildMoved() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onChildMoved` event will be triggered when a child's sort order changes such that its position relative to its siblings changes. The `DataSnapshot` passed to the callback will be for the data of the child that has moved. It is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. - -Signature: - -```typescript -export declare function onChildMoved(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | -| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onChildMoved() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onChildMoved` event will be triggered when a child's sort order changes such that its position relative to its siblings changes. The `DataSnapshot` passed to the callback will be for the data of the child that has moved. It is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. - -Signature: - -```typescript -export declare function onChildMoved(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, options: ListenOptions): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | -| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onChildMoved() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onChildMoved` event will be triggered when a child's sort order changes such that its position relative to its siblings changes. The `DataSnapshot` passed to the callback will be for the data of the child that has moved. It is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. - -Signature: - -```typescript -export declare function onChildMoved(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | -| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | -| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onChildRemoved() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onChildRemoved` event will be triggered once every time a child is removed. The `DataSnapshot` passed into the callback will be the old data for the child that was removed. A child will get removed when either: - -- a client explicitly calls `remove()` on that child or one of its ancestors - a client calls `set(null)` on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) - -Signature: - -```typescript -export declare function onChildRemoved(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | -| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onChildRemoved() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onChildRemoved` event will be triggered once every time a child is removed. The `DataSnapshot` passed into the callback will be the old data for the child that was removed. A child will get removed when either: - -- a client explicitly calls `remove()` on that child or one of its ancestors - a client calls `set(null)` on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) - -Signature: - -```typescript -export declare function onChildRemoved(query: Query, callback: (snapshot: DataSnapshot) => unknown, options: ListenOptions): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | -| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onChildRemoved() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onChildRemoved` event will be triggered once every time a child is removed. The `DataSnapshot` passed into the callback will be the old data for the child that was removed. A child will get removed when either: - -- a client explicitly calls `remove()` on that child or one of its ancestors - a client calls `set(null)` on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) - -Signature: - -```typescript -export declare function onChildRemoved(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | -| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | -| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onDisconnect() - -Returns an `OnDisconnect` object - see [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information on how to use it. - -Signature: - -```typescript -export declare function onDisconnect(ref: DatabaseReference): OnDisconnect; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The reference to add OnDisconnect triggers for. | - -Returns: - -[OnDisconnect](./database.ondisconnect.md#ondisconnect_class) - -## onValue() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onValue` event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The `DataSnapshot` passed to the callback will be for the location at which `on()` was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty `DataSnapshot` (`val()` will return `null`). - -Signature: - -```typescript -export declare function onValue(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot. | -| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onValue() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onValue` event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The `DataSnapshot` passed to the callback will be for the location at which `on()` was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty `DataSnapshot` (`val()` will return `null`). - -Signature: - -```typescript -export declare function onValue(query: Query, callback: (snapshot: DataSnapshot) => unknown, options: ListenOptions): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot. | -| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onValue() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onValue` event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The `DataSnapshot` passed to the callback will be for the location at which `on()` was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty `DataSnapshot` (`val()` will return `null`). - -Signature: - -```typescript -export declare function onValue(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot. | -| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | -| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## orderByChild() - -Creates a new `QueryConstraint` that orders by the specified child key. - -Queries can only order by one key at a time. Calling `orderByChild()` multiple times on the same query is an error. - -Firebase queries allow you to order your data by any child key on the fly. However, if you know in advance what your indexes will be, you can define them via the .indexOn rule in your Security Rules for better performance. See the[https://firebase.google.com/docs/database/security/indexing-data](https://firebase.google.com/docs/database/security/indexing-data) rule for more information. - -You can read more about `orderByChild()` in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). - -Signature: - -```typescript -export declare function orderByChild(path: string): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| path | string | The path to order by. | - -Returns: - -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) - -## orderByKey() - -Creates a new `QueryConstraint` that orders by the key. - -Sorts the results of a query by their (ascending) key values. - -You can read more about `orderByKey()` in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). - -Signature: - -```typescript -export declare function orderByKey(): QueryConstraint; -``` -Returns: - -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) - -## orderByPriority() - -Creates a new `QueryConstraint` that orders by priority. - -Applications need not use priority but can order collections by ordinary properties (see [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data) for alternatives to priority. - -Signature: - -```typescript -export declare function orderByPriority(): QueryConstraint; -``` -Returns: - -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) - -## orderByValue() - -Creates a new `QueryConstraint` that orders by value. - -If the children of a query are all scalar values (string, number, or boolean), you can order the results by their (ascending) values. - -You can read more about `orderByValue()` in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). - -Signature: - -```typescript -export declare function orderByValue(): QueryConstraint; -``` -Returns: - -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) - -## push() - -Generates a new child location using a unique key and returns its `Reference`. - -This is the most common pattern for adding data to a collection of items. - -If you provide a value to `push()`, the value is written to the generated location. If you don't pass a value, nothing is written to the database and the child remains empty (but you can use the `Reference` elsewhere). - -The unique keys generated by `push()` are ordered by the current time, so the resulting list of items is chronologically sorted. The keys are also designed to be unguessable (they contain 72 random bits of entropy). - -See [Append to a list of data](https://firebase.google.com/docs/database/web/lists-of-data#append_to_a_list_of_data). See [The 2^120 Ways to Ensure Unique Identifiers](https://firebase.googleblog.com/2015/02/the-2120-ways-to-ensure-unique_68.html). - -Signature: - -```typescript -export declare function push(parent: DatabaseReference, value?: unknown): ThenableReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| parent | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The parent location. | -| value | unknown | Optional value to be written at the generated location. | - -Returns: - -[ThenableReference](./database.thenablereference.md#thenablereference_interface) - -Combined `Promise` and `Reference`; resolves when write is complete, but can be used immediately as the `Reference` to the child location. - -## query() - -Creates a new immutable instance of `Query` that is extended to also include additional query constraints. - -Signature: - -```typescript -export declare function query(query: Query, ...queryConstraints: QueryConstraint[]): Query; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The Query instance to use as a base for the new constraints. | -| queryConstraints | [QueryConstraint](./database.queryconstraint.md#queryconstraint_class)\[\] | The list of QueryConstraints to apply. | - -Returns: - -[Query](./database.query.md#query_interface) - -## Exceptions - -if any of the provided query constraints cannot be combined with the existing or new constraints. - -## ref() - -Returns a `Reference` representing the location in the Database corresponding to the provided path. If no path is provided, the `Reference` will point to the root of the Database. - -Signature: - -```typescript -export declare function ref(db: Database, path?: string): DatabaseReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| db | [Database](./database.database.md#database_class) | The database instance to obtain a reference for. | -| path | string | Optional path representing the location the returned Reference will point. If not provided, the returned Reference will point to the root of the Database. | - -Returns: - -[DatabaseReference](./database.databasereference.md#databasereference_interface) - -If a path is provided, a `Reference` pointing to the provided path. Otherwise, a `Reference` pointing to the root of the Database. - -## refFromURL() - -Returns a `Reference` representing the location in the Database corresponding to the provided Firebase URL. - -An exception is thrown if the URL is not a valid Firebase Database URL or it has a different domain than the current `Database` instance. - -Note that all query parameters (`orderBy`, `limitToLast`, etc.) are ignored and are not applied to the returned `Reference`. - -Signature: - -```typescript -export declare function refFromURL(db: Database, url: string): DatabaseReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| db | [Database](./database.database.md#database_class) | The database instance to obtain a reference for. | -| url | string | The Firebase URL at which the returned Reference will point. | - -Returns: - -[DatabaseReference](./database.databasereference.md#databasereference_interface) - -A `Reference` pointing to the provided Firebase URL. - -## remove() - -Removes the data at this Database location. - -Any data at child locations will also be deleted. - -The effect of the remove will be visible immediately and the corresponding event 'value' will be triggered. Synchronization of the remove to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the onComplete callback will be called asynchronously after synchronization has finished. - -Signature: - -```typescript -export declare function remove(ref: DatabaseReference): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location to remove. | - -Returns: - -Promise<void> - -Resolves when remove on server is complete. - -## runTransaction() - -Atomically modifies the data at this location. - -Atomically modify the data at this location. Unlike a normal `set()`, which just overwrites the data regardless of its previous value, `runTransaction()` is used to modify the existing value to a new value, ensuring there are no conflicts with other clients writing to the same location at the same time. - -To accomplish this, you pass `runTransaction()` an update function which is used to transform the current value into a new value. If another client writes to the location before your new value is successfully written, your update function will be called again with the new current value, and the write will be retried. This will happen repeatedly until your write succeeds without conflict or you abort the transaction by not returning a value from your update function. - -Note: Modifying data with `set()` will cancel any pending transactions at that location, so extreme care should be taken if mixing `set()` and `runTransaction()` to update the same data. - -Note: When using transactions with Security and Firebase Rules in place, be aware that a client needs `.read` access in addition to `.write` access in order to perform a transaction. This is because the client-side nature of transactions requires the client to read the data in order to transactionally update it. - -Signature: - -```typescript -export declare function runTransaction(ref: DatabaseReference, transactionUpdate: (currentData: any) => unknown, options?: TransactionOptions): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location to atomically modify. | -| transactionUpdate | (currentData: any) => unknown | A developer-supplied function which will be passed the current data stored at this location (as a JavaScript object). The function should return the new value it would like written (as a JavaScript object). If undefined is returned (i.e. you return with no arguments) the transaction will be aborted and the data at this location will not be modified. | -| options | [TransactionOptions](./database.transactionoptions.md#transactionoptions_interface) | An options object to configure transactions. | - -Returns: - -Promise<[TransactionResult](./database.transactionresult.md#transactionresult_class)> - -A `Promise` that can optionally be used instead of the `onComplete` callback to handle success and failure. - -## serverTimestamp() - -Returns a placeholder value for auto-populating the current timestamp (time since the Unix epoch, in milliseconds) as determined by the Firebase servers. - -Signature: - -```typescript -export declare function serverTimestamp(): object; -``` -Returns: - -object - -## set() - -Writes data to this Database location. - -This will overwrite any data at this location and all child locations. - -The effect of the write will be visible immediately, and the corresponding events ("value", "child\_added", etc.) will be triggered. Synchronization of the data to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the `onComplete` callback will be called asynchronously after synchronization has finished. - -Passing `null` for the new value is equivalent to calling `remove()`; namely, all data at this location and all child locations will be deleted. - -`set()` will remove any priority stored at this location, so if priority is meant to be preserved, you need to use `setWithPriority()` instead. - -Note that modifying data with `set()` will cancel any pending transactions at that location, so extreme care should be taken if mixing `set()` and `transaction()` to modify the same data. - -A single `set()` will generate a single "value" event at the location where the `set()` was performed. - -Signature: - -```typescript -export declare function set(ref: DatabaseReference, value: unknown): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location to write to. | -| value | unknown | The value to be written (string, number, boolean, object, array, or null). | - -Returns: - -Promise<void> - -Resolves when write to server is complete. - -## setPriority() - -Sets a priority for the data at this Database location. - -Applications need not use priority but can order collections by ordinary properties (see [Sorting and filtering data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) ). - -Signature: - -```typescript -export declare function setPriority(ref: DatabaseReference, priority: string | number | null): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location to write to. | -| priority | string \| number \| null | The priority to be written (string, number, or null). | - -Returns: - -Promise<void> - -Resolves when write to server is complete. - -## setWithPriority() - -Writes data the Database location. Like `set()` but also specifies the priority for that data. - -Applications need not use priority but can order collections by ordinary properties (see [Sorting and filtering data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) ). - -Signature: - -```typescript -export declare function setWithPriority(ref: DatabaseReference, value: unknown, priority: string | number | null): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location to write to. | -| value | unknown | The value to be written (string, number, boolean, object, array, or null). | -| priority | string \| number \| null | The priority to be written (string, number, or null). | - -Returns: - -Promise<void> - -Resolves when write to server is complete. - -## startAfter() - -Creates a `QueryConstraint` with the specified starting point (exclusive). - -Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. - -The starting point is exclusive. If only a value is provided, children with a value greater than the specified value will be included in the query. If a key is specified, then children must have a value greater than or equal to the specified value and a a key name greater than the specified key. - -Signature: - -```typescript -export declare function startAfter(value: number | string | boolean | null, key?: string): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| value | number \| string \| boolean \| null | The value to start after. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | -| key | string | The child key to start after. This argument is only allowed if ordering by child, value, or priority. | - -Returns: - -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) - -## startAt() - -Creates a `QueryConstraint` with the specified starting point. - -Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. - -The starting point is inclusive, so children with exactly the specified value will be included in the query. The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have a key name greater than or equal to the specified key. - -You can read more about `startAt()` in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). - -Signature: - -```typescript -export declare function startAt(value?: number | string | boolean | null, key?: string): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| value | number \| string \| boolean \| null | The value to start at. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | -| key | string | The child key to start at. This argument is only allowed if ordering by child, value, or priority. | - -Returns: - -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) - -## update() - -Writes multiple values to the Database at once. - -The `values` argument contains multiple property-value pairs that will be written to the Database together. Each child property can either be a simple property (for example, "name") or a relative path (for example, "name/first") from the current location to the data to update. - -As opposed to the `set()` method, `update()` can be use to selectively update only the referenced properties at the current location (instead of replacing all the child properties at the current location). - -The effect of the write will be visible immediately, and the corresponding events ('value', 'child\_added', etc.) will be triggered. Synchronization of the data to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the `onComplete` callback will be called asynchronously after synchronization has finished. - -A single `update()` will generate a single "value" event at the location where the `update()` was performed, regardless of how many children were modified. - -Note that modifying data with `update()` will cancel any pending transactions at that location, so extreme care should be taken if mixing `update()` and `transaction()` to modify the same data. - -Passing `null` to `update()` will remove the data at this location. - -See [Introducing multi-location updates and more](https://firebase.googleblog.com/2015/09/introducing-multi-location-updates-and_86.html). - -Signature: - -```typescript -export declare function update(ref: DatabaseReference, values: object): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location to write to. | -| values | object | Object containing multiple values. | - -Returns: - -Promise<void> - -Resolves when update on server is complete. - -## EventType - -One of the following strings: "value", "child\_added", "child\_changed", "child\_removed", or "child\_moved." - -Signature: - -```typescript -export declare type EventType = 'value' | 'child_added' | 'child_changed' | 'child_moved' | 'child_removed'; -``` - -## QueryConstraintType - -Describes the different query constraints available in this SDK. - -Signature: - -```typescript -export declare type QueryConstraintType = 'endAt' | 'endBefore' | 'startAt' | 'startAfter' | 'limitToFirst' | 'limitToLast' | 'orderByChild' | 'orderByKey' | 'orderByPriority' | 'orderByValue' | 'equalTo'; -``` - -## Unsubscribe - -A callback that can invoked to remove a listener. - -Signature: - -```typescript -export declare type Unsubscribe = () => void; -``` diff --git a/docs-devsite/database.ondisconnect.md b/docs-devsite/database.ondisconnect.md deleted file mode 100644 index b7ed5075365..00000000000 --- a/docs-devsite/database.ondisconnect.md +++ /dev/null @@ -1,143 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# OnDisconnect class -The `onDisconnect` class allows you to write or clear data when your client disconnects from the Database server. These updates occur whether your client disconnects cleanly or not, so you can rely on them to clean up data even if a connection is dropped or a client crashes. - -The `onDisconnect` class is most commonly used to manage presence in applications where it is useful to detect how many clients are connected and when other clients disconnect. See [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information. - -To avoid problems when a connection is dropped before the requests can be transferred to the Database server, these functions should be called before writing any data. - -Note that `onDisconnect` operations are only triggered once. If you want an operation to occur each time a disconnect occurs, you'll need to re-establish the `onDisconnect` operations each time you reconnect. - -Signature: - -```typescript -export declare class OnDisconnect -``` - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [cancel()](./database.ondisconnect.md#ondisconnectcancel) | | Cancels all previously queued onDisconnect() set or update events for this location and all children.If a write has been queued for this location via a set() or update() at a parent location, the write at this location will be canceled, though writes to sibling locations will still occur. | -| [remove()](./database.ondisconnect.md#ondisconnectremove) | | Ensures the data at this location is deleted when the client is disconnected (due to closing the browser, navigating to a new page, or network issues). | -| [set(value)](./database.ondisconnect.md#ondisconnectset) | | Ensures the data at this location is set to the specified value when the client is disconnected (due to closing the browser, navigating to a new page, or network issues).set() is especially useful for implementing "presence" systems, where a value should be changed or cleared when a user disconnects so that they appear "offline" to other users. See [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information.Note that onDisconnect operations are only triggered once. If you want an operation to occur each time a disconnect occurs, you'll need to re-establish the onDisconnect operations each time. | -| [setWithPriority(value, priority)](./database.ondisconnect.md#ondisconnectsetwithpriority) | | Ensures the data at this location is set to the specified value and priority when the client is disconnected (due to closing the browser, navigating to a new page, or network issues). | -| [update(values)](./database.ondisconnect.md#ondisconnectupdate) | | Writes multiple values at this location when the client is disconnected (due to closing the browser, navigating to a new page, or network issues).The values argument contains multiple property-value pairs that will be written to the Database together. Each child property can either be a simple property (for example, "name") or a relative path (for example, "name/first") from the current location to the data to update.As opposed to the set() method, update() can be use to selectively update only the referenced properties at the current location (instead of replacing all the child properties at the current location). | - -## OnDisconnect.cancel() - -Cancels all previously queued `onDisconnect()` set or update events for this location and all children. - -If a write has been queued for this location via a `set()` or `update()` at a parent location, the write at this location will be canceled, though writes to sibling locations will still occur. - -Signature: - -```typescript -cancel(): Promise; -``` -Returns: - -Promise<void> - -Resolves when synchronization to the server is complete. - -## OnDisconnect.remove() - -Ensures the data at this location is deleted when the client is disconnected (due to closing the browser, navigating to a new page, or network issues). - -Signature: - -```typescript -remove(): Promise; -``` -Returns: - -Promise<void> - -Resolves when synchronization to the server is complete. - -## OnDisconnect.set() - -Ensures the data at this location is set to the specified value when the client is disconnected (due to closing the browser, navigating to a new page, or network issues). - -`set()` is especially useful for implementing "presence" systems, where a value should be changed or cleared when a user disconnects so that they appear "offline" to other users. See [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information. - -Note that `onDisconnect` operations are only triggered once. If you want an operation to occur each time a disconnect occurs, you'll need to re-establish the `onDisconnect` operations each time. - -Signature: - -```typescript -set(value: unknown): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| value | unknown | The value to be written to this location on disconnect (can be an object, array, string, number, boolean, or null). | - -Returns: - -Promise<void> - -Resolves when synchronization to the Database is complete. - -## OnDisconnect.setWithPriority() - -Ensures the data at this location is set to the specified value and priority when the client is disconnected (due to closing the browser, navigating to a new page, or network issues). - -Signature: - -```typescript -setWithPriority(value: unknown, priority: number | string | null): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| value | unknown | The value to be written to this location on disconnect (can be an object, array, string, number, boolean, or null). | -| priority | number \| string \| null | The priority to be written (string, number, or null). | - -Returns: - -Promise<void> - -Resolves when synchronization to the Database is complete. - -## OnDisconnect.update() - -Writes multiple values at this location when the client is disconnected (due to closing the browser, navigating to a new page, or network issues). - -The `values` argument contains multiple property-value pairs that will be written to the Database together. Each child property can either be a simple property (for example, "name") or a relative path (for example, "name/first") from the current location to the data to update. - -As opposed to the `set()` method, `update()` can be use to selectively update only the referenced properties at the current location (instead of replacing all the child properties at the current location). - -Signature: - -```typescript -update(values: object): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| values | object | Object containing multiple values. | - -Returns: - -Promise<void> - -Resolves when synchronization to the Database is complete. - diff --git a/docs-devsite/database.query.md b/docs-devsite/database.query.md deleted file mode 100644 index 8ef7b8f8e46..00000000000 --- a/docs-devsite/database.query.md +++ /dev/null @@ -1,108 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Query interface -A `Query` sorts and filters the data at a Database location so only a subset of the child data is included. This can be used to order a collection of data by some attribute (for example, height of dinosaurs) as well as to restrict a large list of items (for example, chat messages) down to a number suitable for synchronizing to the client. Queries are created by chaining together one or more of the filter methods defined here. - -Just as with a `DatabaseReference`, you can receive data from a `Query` by using the `on*()` methods. You will only receive events and `DataSnapshot`s for the subset of the data that matches your query. - -See [https://firebase.google.com/docs/database/web/lists-of-data\#sorting\_and\_filtering\_data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) for more information. - -Signature: - -```typescript -export declare interface Query -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [ref](./database.query.md#queryref) | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The DatabaseReference for the Query's location. | - -## Methods - -| Method | Description | -| --- | --- | -| [isEqual(other)](./database.query.md#queryisequal) | Returns whether or not the current and provided queries represent the same location, have the same query parameters, and are from the same instance of FirebaseApp.Two DatabaseReference objects are equivalent if they represent the same location and are from the same instance of FirebaseApp.Two Query objects are equivalent if they represent the same location, have the same query parameters, and are from the same instance of FirebaseApp. Equivalent queries share the same sort order, limits, and starting and ending points. | -| [toJSON()](./database.query.md#querytojson) | Returns a JSON-serializable representation of this object. | -| [toString()](./database.query.md#querytostring) | Gets the absolute URL for this location.The toString() method returns a URL that is ready to be put into a browser, curl command, or a refFromURL() call. Since all of those expect the URL to be url-encoded, toString() returns an encoded URL.Append '.json' to the returned URL when typed into a browser to download JSON-formatted data. If the location is secured (that is, not publicly readable), you will get a permission-denied error. | - -## Query.ref - -The `DatabaseReference` for the `Query`'s location. - -Signature: - -```typescript -readonly ref: DatabaseReference; -``` - -## Query.isEqual() - -Returns whether or not the current and provided queries represent the same location, have the same query parameters, and are from the same instance of `FirebaseApp`. - -Two `DatabaseReference` objects are equivalent if they represent the same location and are from the same instance of `FirebaseApp`. - -Two `Query` objects are equivalent if they represent the same location, have the same query parameters, and are from the same instance of `FirebaseApp`. Equivalent queries share the same sort order, limits, and starting and ending points. - -Signature: - -```typescript -isEqual(other: Query | null): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| other | [Query](./database.query.md#query_interface) \| null | The query to compare against. | - -Returns: - -boolean - -Whether or not the current and provided queries are equivalent. - -## Query.toJSON() - -Returns a JSON-serializable representation of this object. - -Signature: - -```typescript -toJSON(): string; -``` -Returns: - -string - -A JSON-serializable representation of this object. - -## Query.toString() - -Gets the absolute URL for this location. - -The `toString()` method returns a URL that is ready to be put into a browser, curl command, or a `refFromURL()` call. Since all of those expect the URL to be url-encoded, `toString()` returns an encoded URL. - -Append '.json' to the returned URL when typed into a browser to download JSON-formatted data. If the location is secured (that is, not publicly readable), you will get a permission-denied error. - -Signature: - -```typescript -toString(): string; -``` -Returns: - -string - -The absolute URL for this location. - diff --git a/docs-devsite/database.queryconstraint.md b/docs-devsite/database.queryconstraint.md deleted file mode 100644 index fe98c6badf3..00000000000 --- a/docs-devsite/database.queryconstraint.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryConstraint class -A `QueryConstraint` is used to narrow the set of documents returned by a Database query. `QueryConstraint`s are created by invoking [endAt()](./database.md#endat), [endBefore()](./database.md#endbefore), [startAt()](./database.md#startat), [startAfter()](./database.md#startafter), [limitToFirst()](./database.md#limittofirst), [limitToLast()](./database.md#limittolast), [orderByChild()](./database.md#orderbychild), [orderByChild()](./database.md#orderbychild), [orderByKey()](./database.md#orderbykey) , [orderByPriority()](./database.md#orderbypriority) , [orderByValue()](./database.md#orderbyvalue) or [equalTo()](./database.md#equalto) and can then be passed to [query()](./database.md#query) to create a new query instance that also contains this `QueryConstraint`. - -Signature: - -```typescript -export declare abstract class QueryConstraint -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./database.queryconstraint.md#queryconstrainttype) | | [QueryConstraintType](./database.md#queryconstrainttype) | The type of this query constraints | - -## QueryConstraint.type - -The type of this query constraints - -Signature: - -```typescript -abstract readonly type: QueryConstraintType; -``` diff --git a/docs-devsite/database.thenablereference.md b/docs-devsite/database.thenablereference.md deleted file mode 100644 index b6231d2bd03..00000000000 --- a/docs-devsite/database.thenablereference.md +++ /dev/null @@ -1,21 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ThenableReference interface -A `Promise` that can also act as a `DatabaseReference` when returned by [push()](./database.md#push). The reference is available immediately and the `Promise` resolves as the write to the backend completes. - -Signature: - -```typescript -export declare interface ThenableReference extends DatabaseReference, Pick, 'then' | 'catch'> -``` -Extends: [DatabaseReference](./database.databasereference.md#databasereference_interface), Pick<Promise<[DatabaseReference](./database.databasereference.md#databasereference_interface)>, 'then' \| 'catch'> - diff --git a/docs-devsite/database.transactionoptions.md b/docs-devsite/database.transactionoptions.md deleted file mode 100644 index 0dee85c3a99..00000000000 --- a/docs-devsite/database.transactionoptions.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# TransactionOptions interface -An options object to configure transactions. - -Signature: - -```typescript -export declare interface TransactionOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [applyLocally](./database.transactionoptions.md#transactionoptionsapplylocally) | boolean | By default, events are raised each time the transaction update function runs. So if it is run multiple times, you may see intermediate states. You can set this to false to suppress these intermediate states and instead wait until the transaction has completed before events are raised. | - -## TransactionOptions.applyLocally - -By default, events are raised each time the transaction update function runs. So if it is run multiple times, you may see intermediate states. You can set this to false to suppress these intermediate states and instead wait until the transaction has completed before events are raised. - -Signature: - -```typescript -readonly applyLocally?: boolean; -``` diff --git a/docs-devsite/database.transactionresult.md b/docs-devsite/database.transactionresult.md deleted file mode 100644 index aad84fd6a6b..00000000000 --- a/docs-devsite/database.transactionresult.md +++ /dev/null @@ -1,66 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# TransactionResult class -A type for the resolve value of [runTransaction()](./database.md#runtransaction). - -Signature: - -```typescript -export declare class TransactionResult -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [committed](./database.transactionresult.md#transactionresultcommitted) | | boolean | Whether the transaction was successfully committed. | -| [snapshot](./database.transactionresult.md#transactionresultsnapshot) | | [DataSnapshot](./database.datasnapshot.md#datasnapshot_class) | The resulting data snapshot. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [toJSON()](./database.transactionresult.md#transactionresulttojson) | | Returns a JSON-serializable representation of this object. | - -## TransactionResult.committed - -Whether the transaction was successfully committed. - -Signature: - -```typescript -readonly committed: boolean; -``` - -## TransactionResult.snapshot - -The resulting data snapshot. - -Signature: - -```typescript -readonly snapshot: DataSnapshot; -``` - -## TransactionResult.toJSON() - -Returns a JSON-serializable representation of this object. - -Signature: - -```typescript -toJSON(): object; -``` -Returns: - -object - diff --git a/docs-devsite/firestore.md b/docs-devsite/firestore.md deleted file mode 100644 index c8c647cf611..00000000000 --- a/docs-devsite/firestore.md +++ /dev/null @@ -1,19 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# firestore package -Cloud Firestore - -| Entry Point | Description | -| --- | --- | -| [/](./firestore_.md#@firebase/firestore) | | -| [/lite](./firestore_lite.md#@firebase/firestore/lite) | | - diff --git a/docs-devsite/firestore_.aggregatefield.md b/docs-devsite/firestore_.aggregatefield.md deleted file mode 100644 index 0c3957520b3..00000000000 --- a/docs-devsite/firestore_.aggregatefield.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AggregateField class -Represents an aggregation that can be performed by Firestore. - -Signature: - -```typescript -export declare class AggregateField -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_.aggregatefield.md#aggregatefieldtype) | | string | A type string to uniquely identify instances of this class. | - -## AggregateField.type - -A type string to uniquely identify instances of this class. - -Signature: - -```typescript -type: string; -``` diff --git a/docs-devsite/firestore_.aggregatequerysnapshot.md b/docs-devsite/firestore_.aggregatequerysnapshot.md deleted file mode 100644 index 1cf63b5db8b..00000000000 --- a/docs-devsite/firestore_.aggregatequerysnapshot.md +++ /dev/null @@ -1,70 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AggregateQuerySnapshot class -The results of executing an aggregation query. - -Signature: - -```typescript -export declare class AggregateQuerySnapshot -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [query](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshotquery) | | [Query](./firestore_.query.md#query_class)<unknown> | The underlying query over which the aggregations recorded in this AggregateQuerySnapshot were performed. | -| [type](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshottype) | | (not declared) | A type string to uniquely identify instances of this class. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [data()](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshotdata) | | Returns the results of the aggregations performed over the underlying query.The keys of the returned object will be the same as those of the AggregateSpec object specified to the aggregation method, and the values will be the corresponding aggregation result. | - -## AggregateQuerySnapshot.query - -The underlying query over which the aggregations recorded in this `AggregateQuerySnapshot` were performed. - -Signature: - -```typescript -readonly query: Query; -``` - -## AggregateQuerySnapshot.type - -A type string to uniquely identify instances of this class. - -Signature: - -```typescript -readonly type = "AggregateQuerySnapshot"; -``` - -## AggregateQuerySnapshot.data() - -Returns the results of the aggregations performed over the underlying query. - -The keys of the returned object will be the same as those of the `AggregateSpec` object specified to the aggregation method, and the values will be the corresponding aggregation result. - -Signature: - -```typescript -data(): AggregateSpecData; -``` -Returns: - -[AggregateSpecData](./firestore_.md#aggregatespecdata)<T> - -The results of the aggregations performed over the underlying query. - diff --git a/docs-devsite/firestore_.aggregatespec.md b/docs-devsite/firestore_.aggregatespec.md deleted file mode 100644 index be06b6941f3..00000000000 --- a/docs-devsite/firestore_.aggregatespec.md +++ /dev/null @@ -1,19 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AggregateSpec interface -A type whose property values are all `AggregateField` objects. - -Signature: - -```typescript -export declare interface AggregateSpec -``` diff --git a/docs-devsite/firestore_.bytes.md b/docs-devsite/firestore_.bytes.md deleted file mode 100644 index 411abe327c5..00000000000 --- a/docs-devsite/firestore_.bytes.md +++ /dev/null @@ -1,138 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Bytes class -An immutable object representing an array of bytes. - -Signature: - -```typescript -export declare class Bytes -``` - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [fromBase64String(base64)](./firestore_.bytes.md#bytesfrombase64string) | static | Creates a new Bytes object from the given Base64 string, converting it to bytes. | -| [fromUint8Array(array)](./firestore_.bytes.md#bytesfromuint8array) | static | Creates a new Bytes object from the given Uint8Array. | -| [isEqual(other)](./firestore_.bytes.md#bytesisequal) | | Returns true if this Bytes object is equal to the provided one. | -| [toBase64()](./firestore_.bytes.md#bytestobase64) | | Returns the underlying bytes as a Base64-encoded string. | -| [toString()](./firestore_.bytes.md#bytestostring) | | Returns a string representation of the Bytes object. | -| [toUint8Array()](./firestore_.bytes.md#bytestouint8array) | | Returns the underlying bytes in a new Uint8Array. | - -## Bytes.fromBase64String() - -Creates a new `Bytes` object from the given Base64 string, converting it to bytes. - -Signature: - -```typescript -static fromBase64String(base64: string): Bytes; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| base64 | string | The Base64 string used to create the Bytes object. | - -Returns: - -[Bytes](./firestore_.bytes.md#bytes_class) - -## Bytes.fromUint8Array() - -Creates a new `Bytes` object from the given Uint8Array. - -Signature: - -```typescript -static fromUint8Array(array: Uint8Array): Bytes; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| array | Uint8Array | The Uint8Array used to create the Bytes object. | - -Returns: - -[Bytes](./firestore_.bytes.md#bytes_class) - -## Bytes.isEqual() - -Returns true if this `Bytes` object is equal to the provided one. - -Signature: - -```typescript -isEqual(other: Bytes): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| other | [Bytes](./firestore_.bytes.md#bytes_class) | The Bytes object to compare against. | - -Returns: - -boolean - -true if this `Bytes` object is equal to the provided one. - -## Bytes.toBase64() - -Returns the underlying bytes as a Base64-encoded string. - -Signature: - -```typescript -toBase64(): string; -``` -Returns: - -string - -The Base64-encoded string created from the `Bytes` object. - -## Bytes.toString() - -Returns a string representation of the `Bytes` object. - -Signature: - -```typescript -toString(): string; -``` -Returns: - -string - -A string representation of the `Bytes` object. - -## Bytes.toUint8Array() - -Returns the underlying bytes in a new `Uint8Array`. - -Signature: - -```typescript -toUint8Array(): Uint8Array; -``` -Returns: - -Uint8Array - -The Uint8Array created from the `Bytes` object. - diff --git a/docs-devsite/firestore_.collectionreference.md b/docs-devsite/firestore_.collectionreference.md deleted file mode 100644 index 56c81c6b245..00000000000 --- a/docs-devsite/firestore_.collectionreference.md +++ /dev/null @@ -1,121 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# CollectionReference class -A `CollectionReference` object can be used for adding documents, getting document references, and querying for documents (using [query()](./firestore_.md#query)). - -Signature: - -```typescript -export declare class CollectionReference extends Query -``` -Extends: [Query](./firestore_.query.md#query_class)<T> - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [id](./firestore_.collectionreference.md#collectionreferenceid) | | string | The collection's identifier. | -| [parent](./firestore_.collectionreference.md#collectionreferenceparent) | | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> \| null | A reference to the containing DocumentReference if this is a subcollection. If this isn't a subcollection, the reference is null. | -| [path](./firestore_.collectionreference.md#collectionreferencepath) | | string | A string representing the path of the referenced collection (relative to the root of the database). | -| [type](./firestore_.collectionreference.md#collectionreferencetype) | | (not declared) | The type of this Firestore reference. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [withConverter(converter)](./firestore_.collectionreference.md#collectionreferencewithconverter) | | Applies a custom data converter to this CollectionReference, allowing you to use your own custom model objects with Firestore. When you call [addDoc()](./firestore_.md#adddoc) with the returned CollectionReference instance, the provided converter will convert between Firestore data and your custom type U. | -| [withConverter(converter)](./firestore_.collectionreference.md#collectionreferencewithconverter) | | Removes the current converter. | - -## CollectionReference.id - -The collection's identifier. - -Signature: - -```typescript -get id(): string; -``` - -## CollectionReference.parent - -A reference to the containing `DocumentReference` if this is a subcollection. If this isn't a subcollection, the reference is null. - -Signature: - -```typescript -get parent(): DocumentReference | null; -``` - -## CollectionReference.path - -A string representing the path of the referenced collection (relative to the root of the database). - -Signature: - -```typescript -get path(): string; -``` - -## CollectionReference.type - -The type of this Firestore reference. - -Signature: - -```typescript -readonly type = "collection"; -``` - -## CollectionReference.withConverter() - -Applies a custom data converter to this `CollectionReference`, allowing you to use your own custom model objects with Firestore. When you call [addDoc()](./firestore_.md#adddoc) with the returned `CollectionReference` instance, the provided converter will convert between Firestore data and your custom type `U`. - -Signature: - -```typescript -withConverter(converter: FirestoreDataConverter): CollectionReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| converter | [FirestoreDataConverter](./firestore_.firestoredataconverter.md#firestoredataconverter_interface)<U> | Converts objects to and from Firestore. | - -Returns: - -[CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<U> - -A `CollectionReference` that uses the provided converter. - -## CollectionReference.withConverter() - -Removes the current converter. - -Signature: - -```typescript -withConverter(converter: null): CollectionReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| converter | null | null removes the current converter. | - -Returns: - -[CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> - -A `CollectionReference` that does not use a converter. - diff --git a/docs-devsite/firestore_.documentchange.md b/docs-devsite/firestore_.documentchange.md deleted file mode 100644 index afef795956d..00000000000 --- a/docs-devsite/firestore_.documentchange.md +++ /dev/null @@ -1,68 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# DocumentChange interface -A `DocumentChange` represents a change to the documents matching a query. It contains the document affected and the type of change that occurred. - -Signature: - -```typescript -export declare interface DocumentChange -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [doc](./firestore_.documentchange.md#documentchangedoc) | [QueryDocumentSnapshot](./firestore_.querydocumentsnapshot.md#querydocumentsnapshot_class)<T> | The document affected by this change. | -| [newIndex](./firestore_.documentchange.md#documentchangenewindex) | number | The index of the changed document in the result set immediately after this DocumentChange (i.e. supposing that all prior DocumentChange objects and the current DocumentChange object have been applied). Is -1 for 'removed' events. | -| [oldIndex](./firestore_.documentchange.md#documentchangeoldindex) | number | The index of the changed document in the result set immediately prior to this DocumentChange (i.e. supposing that all prior DocumentChange objects have been applied). Is -1 for 'added' events. | -| [type](./firestore_.documentchange.md#documentchangetype) | [DocumentChangeType](./firestore_.md#documentchangetype) | The type of change ('added', 'modified', or 'removed'). | - -## DocumentChange.doc - -The document affected by this change. - -Signature: - -```typescript -readonly doc: QueryDocumentSnapshot; -``` - -## DocumentChange.newIndex - -The index of the changed document in the result set immediately after this `DocumentChange` (i.e. supposing that all prior `DocumentChange` objects and the current `DocumentChange` object have been applied). Is -1 for 'removed' events. - -Signature: - -```typescript -readonly newIndex: number; -``` - -## DocumentChange.oldIndex - -The index of the changed document in the result set immediately prior to this `DocumentChange` (i.e. supposing that all prior `DocumentChange` objects have been applied). Is `-1` for 'added' events. - -Signature: - -```typescript -readonly oldIndex: number; -``` - -## DocumentChange.type - -The type of change ('added', 'modified', or 'removed'). - -Signature: - -```typescript -readonly type: DocumentChangeType; -``` diff --git a/docs-devsite/firestore_.documentdata.md b/docs-devsite/firestore_.documentdata.md deleted file mode 100644 index 09b5eb64b48..00000000000 --- a/docs-devsite/firestore_.documentdata.md +++ /dev/null @@ -1,19 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# DocumentData interface -Document data (for use with [setDoc()](./firestore_lite.md#setdoc)) consists of fields mapped to values. - -Signature: - -```typescript -export declare interface DocumentData -``` diff --git a/docs-devsite/firestore_.documentreference.md b/docs-devsite/firestore_.documentreference.md deleted file mode 100644 index 16dff93b9c8..00000000000 --- a/docs-devsite/firestore_.documentreference.md +++ /dev/null @@ -1,142 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# DocumentReference class -A `DocumentReference` refers to a document location in a Firestore database and can be used to write, read, or listen to the location. The document at the referenced location may or may not exist. - -Signature: - -```typescript -export declare class DocumentReference -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [converter](./firestore_.documentreference.md#documentreferenceconverter) | | [FirestoreDataConverter](./firestore_.firestoredataconverter.md#firestoredataconverter_interface)<T> \| null | If provided, the FirestoreDataConverter associated with this instance. | -| [firestore](./firestore_.documentreference.md#documentreferencefirestore) | | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance the document is in. This is useful for performing transactions, for example. | -| [id](./firestore_.documentreference.md#documentreferenceid) | | string | The document's identifier within its collection. | -| [parent](./firestore_.documentreference.md#documentreferenceparent) | | [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | The collection this DocumentReference belongs to. | -| [path](./firestore_.documentreference.md#documentreferencepath) | | string | A string representing the path of the referenced document (relative to the root of the database). | -| [type](./firestore_.documentreference.md#documentreferencetype) | | (not declared) | The type of this Firestore reference. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [withConverter(converter)](./firestore_.documentreference.md#documentreferencewithconverter) | | Applies a custom data converter to this DocumentReference, allowing you to use your own custom model objects with Firestore. When you call [setDoc()](./firestore_lite.md#setdoc), [getDoc()](./firestore_lite.md#getdoc), etc. with the returned DocumentReference instance, the provided converter will convert between Firestore data and your custom type U. | -| [withConverter(converter)](./firestore_.documentreference.md#documentreferencewithconverter) | | Removes the current converter. | - -## DocumentReference.converter - -If provided, the `FirestoreDataConverter` associated with this instance. - -Signature: - -```typescript -readonly converter: FirestoreDataConverter | null; -``` - -## DocumentReference.firestore - -The [Firestore](./firestore_.firestore.md#firestore_class) instance the document is in. This is useful for performing transactions, for example. - -Signature: - -```typescript -readonly firestore: Firestore; -``` - -## DocumentReference.id - -The document's identifier within its collection. - -Signature: - -```typescript -get id(): string; -``` - -## DocumentReference.parent - -The collection this `DocumentReference` belongs to. - -Signature: - -```typescript -get parent(): CollectionReference; -``` - -## DocumentReference.path - -A string representing the path of the referenced document (relative to the root of the database). - -Signature: - -```typescript -get path(): string; -``` - -## DocumentReference.type - -The type of this Firestore reference. - -Signature: - -```typescript -readonly type = "document"; -``` - -## DocumentReference.withConverter() - -Applies a custom data converter to this `DocumentReference`, allowing you to use your own custom model objects with Firestore. When you call [setDoc()](./firestore_lite.md#setdoc), [getDoc()](./firestore_lite.md#getdoc), etc. with the returned `DocumentReference` instance, the provided converter will convert between Firestore data and your custom type `U`. - -Signature: - -```typescript -withConverter(converter: FirestoreDataConverter): DocumentReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| converter | [FirestoreDataConverter](./firestore_.firestoredataconverter.md#firestoredataconverter_interface)<U> | Converts objects to and from Firestore. | - -Returns: - -[DocumentReference](./firestore_.documentreference.md#documentreference_class)<U> - -A `DocumentReference` that uses the provided converter. - -## DocumentReference.withConverter() - -Removes the current converter. - -Signature: - -```typescript -withConverter(converter: null): DocumentReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| converter | null | null removes the current converter. | - -Returns: - -[DocumentReference](./firestore_.documentreference.md#documentreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> - -A `DocumentReference` that does not use a converter. - diff --git a/docs-devsite/firestore_.documentsnapshot.md b/docs-devsite/firestore_.documentsnapshot.md deleted file mode 100644 index 3ac2ec7dcb2..00000000000 --- a/docs-devsite/firestore_.documentsnapshot.md +++ /dev/null @@ -1,146 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# DocumentSnapshot class -A `DocumentSnapshot` contains data read from a document in your Firestore database. The data can be extracted with `.data()` or `.get()` to get a specific field. - -For a `DocumentSnapshot` that points to a non-existing document, any data access will return 'undefined'. You can use the `exists()` method to explicitly verify a document's existence. - -Signature: - -```typescript -export declare class DocumentSnapshot -``` - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)()](./firestore_.documentsnapshot.md#documentsnapshotconstructor) | | Constructs a new instance of the DocumentSnapshot class | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [id](./firestore_.documentsnapshot.md#documentsnapshotid) | | string | Property of the DocumentSnapshot that provides the document's ID. | -| [metadata](./firestore_.documentsnapshot.md#documentsnapshotmetadata) | | [SnapshotMetadata](./firestore_.snapshotmetadata.md#snapshotmetadata_class) | Metadata about the DocumentSnapshot, including information about its source and local modifications. | -| [ref](./firestore_.documentsnapshot.md#documentsnapshotref) | | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | The DocumentReference for the document included in the DocumentSnapshot. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [data(options)](./firestore_.documentsnapshot.md#documentsnapshotdata) | | Retrieves all fields in the document as an Object. Returns undefined if the document doesn't exist.By default, serverTimestamp() values that have not yet been set to their final value will be returned as null. You can override this by passing an options object. | -| [exists()](./firestore_.documentsnapshot.md#documentsnapshotexists) | | Returns whether or not the data exists. True if the document exists. | -| [get(fieldPath, options)](./firestore_.documentsnapshot.md#documentsnapshotget) | | Retrieves the field specified by fieldPath. Returns undefined if the document or field doesn't exist.By default, a serverTimestamp() that has not yet been set to its final value will be returned as null. You can override this by passing an options object. | - -## DocumentSnapshot.(constructor) - -Constructs a new instance of the `DocumentSnapshot` class - -Signature: - -```typescript -protected constructor(); -``` - -## DocumentSnapshot.id - -Property of the `DocumentSnapshot` that provides the document's ID. - -Signature: - -```typescript -get id(): string; -``` - -## DocumentSnapshot.metadata - -Metadata about the `DocumentSnapshot`, including information about its source and local modifications. - -Signature: - -```typescript -readonly metadata: SnapshotMetadata; -``` - -## DocumentSnapshot.ref - -The `DocumentReference` for the document included in the `DocumentSnapshot`. - -Signature: - -```typescript -get ref(): DocumentReference; -``` - -## DocumentSnapshot.data() - -Retrieves all fields in the document as an `Object`. Returns `undefined` if the document doesn't exist. - -By default, `serverTimestamp()` values that have not yet been set to their final value will be returned as `null`. You can override this by passing an options object. - -Signature: - -```typescript -data(options?: SnapshotOptions): T | undefined; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| options | [SnapshotOptions](./firestore_.snapshotoptions.md#snapshotoptions_interface) | An options object to configure how data is retrieved from the snapshot (for example the desired behavior for server timestamps that have not yet been set to their final value). | - -Returns: - -T \| undefined - -An `Object` containing all fields in the document or `undefined` if the document doesn't exist. - -## DocumentSnapshot.exists() - -Returns whether or not the data exists. True if the document exists. - -Signature: - -```typescript -exists(): this is QueryDocumentSnapshot; -``` -Returns: - -this is [QueryDocumentSnapshot](./firestore_.querydocumentsnapshot.md#querydocumentsnapshot_class)<T> - -## DocumentSnapshot.get() - -Retrieves the field specified by `fieldPath`. Returns `undefined` if the document or field doesn't exist. - -By default, a `serverTimestamp()` that has not yet been set to its final value will be returned as `null`. You can override this by passing an options object. - -Signature: - -```typescript -get(fieldPath: string | FieldPath, options?: SnapshotOptions): any; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldPath | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The path (for example 'foo' or 'foo.bar') to a specific field. | -| options | [SnapshotOptions](./firestore_.snapshotoptions.md#snapshotoptions_interface) | An options object to configure how the field is retrieved from the snapshot (for example the desired behavior for server timestamps that have not yet been set to their final value). | - -Returns: - -any - -The data at the specified field location or undefined if no such field exists in the document. - diff --git a/docs-devsite/firestore_.fieldpath.md b/docs-devsite/firestore_.fieldpath.md deleted file mode 100644 index 8a9143f02a8..00000000000 --- a/docs-devsite/firestore_.fieldpath.md +++ /dev/null @@ -1,72 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FieldPath class -A `FieldPath` refers to a field in a document. The path may consist of a single field name (referring to a top-level field in the document), or a list of field names (referring to a nested field in the document). - -Create a `FieldPath` by providing field names. If more than one field name is provided, the path will point to a nested field in a document. - -Signature: - -```typescript -export declare class FieldPath -``` - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(fieldNames)](./firestore_.fieldpath.md#fieldpathconstructor) | | Creates a FieldPath from the provided field names. If more than one field name is provided, the path will point to a nested field in a document. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [isEqual(other)](./firestore_.fieldpath.md#fieldpathisequal) | | Returns true if this FieldPath is equal to the provided one. | - -## FieldPath.(constructor) - -Creates a `FieldPath` from the provided field names. If more than one field name is provided, the path will point to a nested field in a document. - -Signature: - -```typescript -constructor(...fieldNames: string[]); -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldNames | string\[\] | A list of field names. | - -## FieldPath.isEqual() - -Returns true if this `FieldPath` is equal to the provided one. - -Signature: - -```typescript -isEqual(other: FieldPath): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| other | [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The FieldPath to compare against. | - -Returns: - -boolean - -true if this `FieldPath` is equal to the provided one. - diff --git a/docs-devsite/firestore_.fieldvalue.md b/docs-devsite/firestore_.fieldvalue.md deleted file mode 100644 index 62c034583d6..00000000000 --- a/docs-devsite/firestore_.fieldvalue.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FieldValue class -Sentinel values that can be used when writing document fields with `set()` or `update()`. - -Signature: - -```typescript -export declare abstract class FieldValue -``` - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [isEqual(other)](./firestore_.fieldvalue.md#fieldvalueisequal) | | Compares FieldValues for equality. | - -## FieldValue.isEqual() - -Compares `FieldValue`s for equality. - -Signature: - -```typescript -abstract isEqual(other: FieldValue): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| other | [FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) | | - -Returns: - -boolean - diff --git a/docs-devsite/firestore_.firestore.md b/docs-devsite/firestore_.firestore.md deleted file mode 100644 index 01267d5b2d3..00000000000 --- a/docs-devsite/firestore_.firestore.md +++ /dev/null @@ -1,68 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Firestore class -The Cloud Firestore service interface. - -Do not call this constructor directly. Instead, use [getFirestore()](./firestore_.md#getfirestore). - -Signature: - -```typescript -export declare class Firestore -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [app](./firestore_.firestore.md#firestoreapp) | | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this Firestore service instance. | -| [type](./firestore_.firestore.md#firestoretype) | | 'firestore-lite' \| 'firestore' | Whether it's a [Firestore](./firestore_.firestore.md#firestore_class) or Firestore Lite instance. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [toJSON()](./firestore_.firestore.md#firestoretojson) | | Returns a JSON-serializable representation of this Firestore instance. | - -## Firestore.app - -The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this `Firestore` service instance. - -Signature: - -```typescript -get app(): FirebaseApp; -``` - -## Firestore.type - -Whether it's a [Firestore](./firestore_.firestore.md#firestore_class) or Firestore Lite instance. - -Signature: - -```typescript -type: 'firestore-lite' | 'firestore'; -``` - -## Firestore.toJSON() - -Returns a JSON-serializable representation of this `Firestore` instance. - -Signature: - -```typescript -toJSON(): object; -``` -Returns: - -object - diff --git a/docs-devsite/firestore_.firestoredataconverter.md b/docs-devsite/firestore_.firestoredataconverter.md deleted file mode 100644 index f7d80ac4a13..00000000000 --- a/docs-devsite/firestore_.firestoredataconverter.md +++ /dev/null @@ -1,134 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FirestoreDataConverter interface -Converter used by `withConverter()` to transform user objects of type `T` into Firestore data. - -Using the converter allows you to specify generic type arguments when storing and retrieving objects from Firestore. - -Signature: - -```typescript -export declare interface FirestoreDataConverter -``` - -## Methods - -| Method | Description | -| --- | --- | -| [fromFirestore(snapshot, options)](./firestore_.firestoredataconverter.md#firestoredataconverterfromfirestore) | Called by the Firestore SDK to convert Firestore data into an object of type T. You can access your data by calling: snapshot.data(options). | -| [toFirestore(modelObject)](./firestore_.firestoredataconverter.md#firestoredataconvertertofirestore) | Called by the Firestore SDK to convert a custom model object of type T into a plain JavaScript object (suitable for writing directly to the Firestore database). To use set() with merge and mergeFields, toFirestore() must be defined with PartialWithFieldValue<T>.The WithFieldValue<T> type extends T to also allow FieldValues such as [deleteField()](./firestore_.md#deletefield) to be used as property values. | -| [toFirestore(modelObject, options)](./firestore_.firestoredataconverter.md#firestoredataconvertertofirestore) | Called by the Firestore SDK to convert a custom model object of type T into a plain JavaScript object (suitable for writing directly to the Firestore database). Used with [setDoc()](./firestore_.md#setdoc), and with merge:true or mergeFields.The PartialWithFieldValue<T> type extends Partial<T> to allow FieldValues such as [arrayUnion()](./firestore_.md#arrayunion) to be used as property values. It also supports nested Partial by allowing nested fields to be omitted. | - -## FirestoreDataConverter.fromFirestore() - -Called by the Firestore SDK to convert Firestore data into an object of type T. You can access your data by calling: `snapshot.data(options)`. - -Signature: - -```typescript -fromFirestore(snapshot: QueryDocumentSnapshot, options?: SnapshotOptions): T; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| snapshot | [QueryDocumentSnapshot](./firestore_.querydocumentsnapshot.md#querydocumentsnapshot_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> | A QueryDocumentSnapshot containing your data and metadata. | -| options | [SnapshotOptions](./firestore_.snapshotoptions.md#snapshotoptions_interface) | The SnapshotOptions from the initial call to data(). | - -Returns: - -T - -## FirestoreDataConverter.toFirestore() - -Called by the Firestore SDK to convert a custom model object of type `T` into a plain JavaScript object (suitable for writing directly to the Firestore database). To use `set()` with `merge` and `mergeFields`, `toFirestore()` must be defined with `PartialWithFieldValue`. - -The `WithFieldValue` type extends `T` to also allow FieldValues such as [deleteField()](./firestore_.md#deletefield) to be used as property values. - -Signature: - -```typescript -toFirestore(modelObject: WithFieldValue): DocumentData; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| modelObject | [WithFieldValue](./firestore_.md#withfieldvalue)<T> | | - -Returns: - -[DocumentData](./firestore_.documentdata.md#documentdata_interface) - -## FirestoreDataConverter.toFirestore() - -Called by the Firestore SDK to convert a custom model object of type `T` into a plain JavaScript object (suitable for writing directly to the Firestore database). Used with [setDoc()](./firestore_.md#setdoc), and with `merge:true` or `mergeFields`. - -The `PartialWithFieldValue` type extends `Partial` to allow FieldValues such as [arrayUnion()](./firestore_.md#arrayunion) to be used as property values. It also supports nested `Partial` by allowing nested fields to be omitted. - -Signature: - -```typescript -toFirestore(modelObject: PartialWithFieldValue, options: SetOptions): DocumentData; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| modelObject | [PartialWithFieldValue](./firestore_.md#partialwithfieldvalue)<T> | | -| options | [SetOptions](./firestore_.md#setoptions) | | - -Returns: - -[DocumentData](./firestore_.documentdata.md#documentdata_interface) - -### Example - - -```typescript -class Post { - constructor(readonly title: string, readonly author: string) {} - - toString(): string { - return this.title + ', by ' + this.author; - } -} - -const postConverter = { - toFirestore(post: WithFieldValue): DocumentData { - return {title: post.title, author: post.author}; - }, - fromFirestore( - snapshot: QueryDocumentSnapshot, - options: SnapshotOptions - ): Post { - const data = snapshot.data(options)!; - return new Post(data.title, data.author); - } -}; - -const postSnap = await firebase.firestore() - .collection('posts') - .withConverter(postConverter) - .doc().get(); -const post = postSnap.data(); -if (post !== undefined) { - post.title; // string - post.toString(); // Should be defined - post.someNonExistentProperty; // TS error -} - -``` - diff --git a/docs-devsite/firestore_.firestoreerror.md b/docs-devsite/firestore_.firestoreerror.md deleted file mode 100644 index c16cf39541e..00000000000 --- a/docs-devsite/firestore_.firestoreerror.md +++ /dev/null @@ -1,58 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FirestoreError class -An error returned by a Firestore operation. - -Signature: - -```typescript -export declare class FirestoreError extends FirebaseError -``` -Extends: [FirebaseError](./util.firebaseerror.md#firebaseerror_class) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [code](./firestore_.firestoreerror.md#firestoreerrorcode) | | [FirestoreErrorCode](./firestore_.md#firestoreerrorcode) | The backend error code associated with this error. | -| [message](./firestore_.firestoreerror.md#firestoreerrormessage) | | string | A custom error description. | -| [stack](./firestore_.firestoreerror.md#firestoreerrorstack) | | string | The stack of the error. | - -## FirestoreError.code - -The backend error code associated with this error. - -Signature: - -```typescript -readonly code: FirestoreErrorCode; -``` - -## FirestoreError.message - -A custom error description. - -Signature: - -```typescript -readonly message: string; -``` - -## FirestoreError.stack - -The stack of the error. - -Signature: - -```typescript -readonly stack?: string; -``` diff --git a/docs-devsite/firestore_.firestoresettings.md b/docs-devsite/firestore_.firestoresettings.md deleted file mode 100644 index 96fe454cb77..00000000000 --- a/docs-devsite/firestore_.firestoresettings.md +++ /dev/null @@ -1,96 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FirestoreSettings interface -Specifies custom configurations for your Cloud Firestore instance. You must set these before invoking any other methods. - -Signature: - -```typescript -export declare interface FirestoreSettings -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [cacheSizeBytes](./firestore_.firestoresettings.md#firestoresettingscachesizebytes) | number | An approximate cache size threshold for the on-disk data. If the cache grows beyond this size, Firestore will start removing data that hasn't been recently used. The size is not a guarantee that the cache will stay below that size, only that if the cache exceeds the given size, cleanup will be attempted.The default value is 40 MB. The threshold must be set to at least 1 MB, and can be set to CACHE_SIZE_UNLIMITED to disable garbage collection. | -| [experimentalAutoDetectLongPolling](./firestore_.firestoresettings.md#firestoresettingsexperimentalautodetectlongpolling) | boolean | Configures the SDK's underlying transport (WebChannel) to automatically detect if long-polling should be used. This is very similar to experimentalForceLongPolling, but only uses long-polling if required.This setting will likely be enabled by default in future releases and cannot be combined with experimentalForceLongPolling. | -| [experimentalForceLongPolling](./firestore_.firestoresettings.md#firestoresettingsexperimentalforcelongpolling) | boolean | Forces the SDK’s underlying network transport (WebChannel) to use long-polling. Each response from the backend will be closed immediately after the backend sends data (by default responses are kept open in case the backend has more data to send). This avoids incompatibility issues with certain proxies, antivirus software, etc. that incorrectly buffer traffic indefinitely. Use of this option will cause some performance degradation though.This setting cannot be used with experimentalAutoDetectLongPolling and may be removed in a future release. If you find yourself using it to work around a specific network reliability issue, please tell us about it in https://github.com/firebase/firebase-js-sdk/issues/1674. | -| [host](./firestore_.firestoresettings.md#firestoresettingshost) | string | The hostname to connect to. | -| [ignoreUndefinedProperties](./firestore_.firestoresettings.md#firestoresettingsignoreundefinedproperties) | boolean | Whether to skip nested properties that are set to undefined during object serialization. If set to true, these properties are skipped and not written to Firestore. If set to false or omitted, the SDK throws an exception when it encounters properties of type undefined. | -| [ssl](./firestore_.firestoresettings.md#firestoresettingsssl) | boolean | Whether to use SSL when connecting. | - -## FirestoreSettings.cacheSizeBytes - -An approximate cache size threshold for the on-disk data. If the cache grows beyond this size, Firestore will start removing data that hasn't been recently used. The size is not a guarantee that the cache will stay below that size, only that if the cache exceeds the given size, cleanup will be attempted. - -The default value is 40 MB. The threshold must be set to at least 1 MB, and can be set to `CACHE_SIZE_UNLIMITED` to disable garbage collection. - -Signature: - -```typescript -cacheSizeBytes?: number; -``` - -## FirestoreSettings.experimentalAutoDetectLongPolling - -Configures the SDK's underlying transport (WebChannel) to automatically detect if long-polling should be used. This is very similar to `experimentalForceLongPolling`, but only uses long-polling if required. - -This setting will likely be enabled by default in future releases and cannot be combined with `experimentalForceLongPolling`. - -Signature: - -```typescript -experimentalAutoDetectLongPolling?: boolean; -``` - -## FirestoreSettings.experimentalForceLongPolling - -Forces the SDK’s underlying network transport (WebChannel) to use long-polling. Each response from the backend will be closed immediately after the backend sends data (by default responses are kept open in case the backend has more data to send). This avoids incompatibility issues with certain proxies, antivirus software, etc. that incorrectly buffer traffic indefinitely. Use of this option will cause some performance degradation though. - -This setting cannot be used with `experimentalAutoDetectLongPolling` and may be removed in a future release. If you find yourself using it to work around a specific network reliability issue, please tell us about it in https://github.com/firebase/firebase-js-sdk/issues/1674. - -Signature: - -```typescript -experimentalForceLongPolling?: boolean; -``` - -## FirestoreSettings.host - -The hostname to connect to. - -Signature: - -```typescript -host?: string; -``` - -## FirestoreSettings.ignoreUndefinedProperties - -Whether to skip nested properties that are set to `undefined` during object serialization. If set to `true`, these properties are skipped and not written to Firestore. If set to `false` or omitted, the SDK throws an exception when it encounters properties of type `undefined`. - -Signature: - -```typescript -ignoreUndefinedProperties?: boolean; -``` - -## FirestoreSettings.ssl - -Whether to use SSL when connecting. - -Signature: - -```typescript -ssl?: boolean; -``` diff --git a/docs-devsite/firestore_.geopoint.md b/docs-devsite/firestore_.geopoint.md deleted file mode 100644 index d2fd1bd7392..00000000000 --- a/docs-devsite/firestore_.geopoint.md +++ /dev/null @@ -1,117 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# GeoPoint class -An immutable object representing a geographic location in Firestore. The location is represented as latitude/longitude pair. - -Latitude values are in the range of \[-90, 90\]. Longitude values are in the range of \[-180, 180\]. - -Signature: - -```typescript -export declare class GeoPoint -``` - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(latitude, longitude)](./firestore_.geopoint.md#geopointconstructor) | | Creates a new immutable GeoPoint object with the provided latitude and longitude values. | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [latitude](./firestore_.geopoint.md#geopointlatitude) | | number | The latitude of this GeoPoint instance. | -| [longitude](./firestore_.geopoint.md#geopointlongitude) | | number | The longitude of this GeoPoint instance. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [isEqual(other)](./firestore_.geopoint.md#geopointisequal) | | Returns true if this GeoPoint is equal to the provided one. | -| [toJSON()](./firestore_.geopoint.md#geopointtojson) | | Returns a JSON-serializable representation of this GeoPoint. | - -## GeoPoint.(constructor) - -Creates a new immutable `GeoPoint` object with the provided latitude and longitude values. - -Signature: - -```typescript -constructor(latitude: number, longitude: number); -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| latitude | number | The latitude as number between -90 and 90. | -| longitude | number | The longitude as number between -180 and 180. | - -## GeoPoint.latitude - -The latitude of this `GeoPoint` instance. - -Signature: - -```typescript -get latitude(): number; -``` - -## GeoPoint.longitude - -The longitude of this `GeoPoint` instance. - -Signature: - -```typescript -get longitude(): number; -``` - -## GeoPoint.isEqual() - -Returns true if this `GeoPoint` is equal to the provided one. - -Signature: - -```typescript -isEqual(other: GeoPoint): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| other | [GeoPoint](./firestore_.geopoint.md#geopoint_class) | The GeoPoint to compare against. | - -Returns: - -boolean - -true if this `GeoPoint` is equal to the provided one. - -## GeoPoint.toJSON() - -Returns a JSON-serializable representation of this GeoPoint. - -Signature: - -```typescript -toJSON(): { - latitude: number; - longitude: number; - }; -``` -Returns: - -{ latitude: number; longitude: number; } - diff --git a/docs-devsite/firestore_.index.md b/docs-devsite/firestore_.index.md deleted file mode 100644 index 3ea216d6798..00000000000 --- a/docs-devsite/firestore_.index.md +++ /dev/null @@ -1,55 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Index interface -> 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. -> - -The SDK definition of a Firestore index. - -Signature: - -```typescript -export declare interface Index -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [collectionGroup](./firestore_.index.md#indexcollectiongroup) | string | (BETA) The ID of the collection to index. | -| [fields](./firestore_.index.md#indexfields) | [IndexField](./firestore_.indexfield.md#indexfield_interface)\[\] | (BETA) A list of fields to index. | - -## Index.collectionGroup - -> 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. -> - -The ID of the collection to index. - -Signature: - -```typescript -readonly collectionGroup: string; -``` - -## Index.fields - -> 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. -> - -A list of fields to index. - -Signature: - -```typescript -readonly fields?: IndexField[]; -``` diff --git a/docs-devsite/firestore_.indexconfiguration.md b/docs-devsite/firestore_.indexconfiguration.md deleted file mode 100644 index 8a0592e7ed6..00000000000 --- a/docs-devsite/firestore_.indexconfiguration.md +++ /dev/null @@ -1,43 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# IndexConfiguration interface -> 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. -> - -A list of Firestore indexes to speed up local query execution. - -See [JSON Format](https://firebase.google.com/docs/reference/firestore/indexes/#json_format) for a description of the format of the index definition. - -Signature: - -```typescript -export declare interface IndexConfiguration -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [indexes](./firestore_.indexconfiguration.md#indexconfigurationindexes) | [Index](./firestore_.index.md#index_interface)\[\] | (BETA) A list of all Firestore indexes. | - -## IndexConfiguration.indexes - -> 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. -> - -A list of all Firestore indexes. - -Signature: - -```typescript -readonly indexes?: Index[]; -``` diff --git a/docs-devsite/firestore_.indexfield.md b/docs-devsite/firestore_.indexfield.md deleted file mode 100644 index 278e2f63ce8..00000000000 --- a/docs-devsite/firestore_.indexfield.md +++ /dev/null @@ -1,73 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# IndexField interface -> 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. -> - -A single field element in an index configuration. - -Signature: - -```typescript -export declare interface IndexField -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [arrayConfig](./firestore_.indexfield.md#indexfieldarrayconfig) | 'CONTAINS' | (BETA) What type of array index to create. Set to CONTAINS for array-contains and array-contains-any indexes.Only one of arrayConfig or order should be set; | -| [fieldPath](./firestore_.indexfield.md#indexfieldfieldpath) | string | (BETA) The field path to index. | -| [order](./firestore_.indexfield.md#indexfieldorder) | 'ASCENDING' \| 'DESCENDING' | (BETA) What type of array index to create. Set to ASCENDING or 'DESCENDING for ==, !=, <=, <=, in and not-in\` filters.Only one of arrayConfig or order should be set. | - -## IndexField.arrayConfig - -> 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. -> - -What type of array index to create. Set to `CONTAINS` for `array-contains` and `array-contains-any` indexes. - -Only one of `arrayConfig` or `order` should be set; - -Signature: - -```typescript -readonly arrayConfig?: 'CONTAINS'; -``` - -## IndexField.fieldPath - -> 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. -> - -The field path to index. - -Signature: - -```typescript -readonly fieldPath: string; -``` - -## IndexField.order - -> 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. -> - -What type of array index to create. Set to `ASCENDING` or 'DESCENDING` for `==`, `!=`, `<=`, `<=`, `in` and `not-in\` filters. - -Only one of `arrayConfig` or `order` should be set. - -Signature: - -```typescript -readonly order?: 'ASCENDING' | 'DESCENDING'; -``` diff --git a/docs-devsite/firestore_.loadbundletask.md b/docs-devsite/firestore_.loadbundletask.md deleted file mode 100644 index 8b446d5d6e1..00000000000 --- a/docs-devsite/firestore_.loadbundletask.md +++ /dev/null @@ -1,94 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# LoadBundleTask class -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`. - -Signature: - -```typescript -export declare class LoadBundleTask implements PromiseLike -``` -Implements: PromiseLike<[LoadBundleTaskProgress](./firestore_.loadbundletaskprogress.md#loadbundletaskprogress_interface)> - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [catch(onRejected)](./firestore_.loadbundletask.md#loadbundletaskcatch) | | Implements the Promise<LoadBundleTaskProgress>.catch interface. | -| [onProgress(next, error, complete)](./firestore_.loadbundletask.md#loadbundletaskonprogress) | | Registers functions to listen to bundle loading progress events. | -| [then(onFulfilled, onRejected)](./firestore_.loadbundletask.md#loadbundletaskthen) | | Implements the Promise<LoadBundleTaskProgress>.then interface. | - -## LoadBundleTask.catch() - -Implements the `Promise.catch` interface. - -Signature: - -```typescript -catch(onRejected: (a: Error) => R | PromiseLike): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| onRejected | (a: Error) => R \| PromiseLike<R> | Called when an error occurs during bundle loading. | - -Returns: - -Promise<R \| [LoadBundleTaskProgress](./firestore_.loadbundletaskprogress.md#loadbundletaskprogress_interface)> - -## LoadBundleTask.onProgress() - -Registers functions to listen to bundle loading progress events. - -Signature: - -```typescript -onProgress(next?: (progress: LoadBundleTaskProgress) => unknown, error?: (err: Error) => unknown, complete?: () => void): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| next | (progress: [LoadBundleTaskProgress](./firestore_.loadbundletaskprogress.md#loadbundletaskprogress_interface)) => unknown | Called when there is a progress update from bundle loading. Typically next calls occur each time a Firestore document is loaded from the bundle. | -| error | (err: Error) => unknown | Called when an error occurs during bundle loading. The task aborts after reporting the error, and there should be no more updates after this. | -| complete | () => void | Called when the loading task is complete. | - -Returns: - -void - -## LoadBundleTask.then() - -Implements the `Promise.then` interface. - -Signature: - -```typescript -then(onFulfilled?: (a: LoadBundleTaskProgress) => T | PromiseLike, onRejected?: (a: Error) => R | PromiseLike): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| onFulfilled | (a: [LoadBundleTaskProgress](./firestore_.loadbundletaskprogress.md#loadbundletaskprogress_interface)) => T \| PromiseLike<T> | Called on the completion of the loading task with a final LoadBundleTaskProgress update. The update will always have its taskState set to "Success". | -| onRejected | (a: Error) => R \| PromiseLike<R> | Called when an error occurs during bundle loading. | - -Returns: - -Promise<T \| R> - diff --git a/docs-devsite/firestore_.loadbundletaskprogress.md b/docs-devsite/firestore_.loadbundletaskprogress.md deleted file mode 100644 index 98124754928..00000000000 --- a/docs-devsite/firestore_.loadbundletaskprogress.md +++ /dev/null @@ -1,79 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# LoadBundleTaskProgress interface -Represents a progress update or a final state from loading bundles. - -Signature: - -```typescript -export declare interface LoadBundleTaskProgress -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [bytesLoaded](./firestore_.loadbundletaskprogress.md#loadbundletaskprogressbytesloaded) | number | How many bytes have been loaded. | -| [documentsLoaded](./firestore_.loadbundletaskprogress.md#loadbundletaskprogressdocumentsloaded) | number | How many documents have been loaded. | -| [taskState](./firestore_.loadbundletaskprogress.md#loadbundletaskprogresstaskstate) | [TaskState](./firestore_.md#taskstate) | Current task state. | -| [totalBytes](./firestore_.loadbundletaskprogress.md#loadbundletaskprogresstotalbytes) | number | How many bytes are in the bundle being loaded. | -| [totalDocuments](./firestore_.loadbundletaskprogress.md#loadbundletaskprogresstotaldocuments) | number | How many documents are in the bundle being loaded. | - -## LoadBundleTaskProgress.bytesLoaded - -How many bytes have been loaded. - -Signature: - -```typescript -bytesLoaded: number; -``` - -## LoadBundleTaskProgress.documentsLoaded - -How many documents have been loaded. - -Signature: - -```typescript -documentsLoaded: number; -``` - -## LoadBundleTaskProgress.taskState - -Current task state. - -Signature: - -```typescript -taskState: TaskState; -``` - -## LoadBundleTaskProgress.totalBytes - -How many bytes are in the bundle being loaded. - -Signature: - -```typescript -totalBytes: number; -``` - -## LoadBundleTaskProgress.totalDocuments - -How many documents are in the bundle being loaded. - -Signature: - -```typescript -totalDocuments: number; -``` diff --git a/docs-devsite/firestore_.md b/docs-devsite/firestore_.md deleted file mode 100644 index 7fcf1b9426e..00000000000 --- a/docs-devsite/firestore_.md +++ /dev/null @@ -1,2103 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# @firebase/firestore - -## Functions - -| Function | Description | -| --- | --- | -| [addDoc(reference, data)](./firestore_.md#adddoc) | Add a new document to specified CollectionReference with the given data, assigning it a document ID automatically. | -| [aggregateQuerySnapshotEqual(left, right)](./firestore_.md#aggregatequerysnapshotequal) | Compares two AggregateQuerySnapshot instances for equality.Two AggregateQuerySnapshot instances are considered "equal" if they have underlying queries that compare equal, and the same data. | -| [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. | -| [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. | -| [collection(firestore, path, pathSegments)](./firestore_.md#collection) | Gets a CollectionReference instance that refers to the collection at the specified absolute path. | -| [collection(reference, path, pathSegments)](./firestore_.md#collection) | Gets a CollectionReference instance that refers to a subcollection of reference at the the specified relative path. | -| [collection(reference, path, pathSegments)](./firestore_.md#collection) | Gets a CollectionReference instance that refers to a subcollection of reference at the the specified relative path. | -| [collectionGroup(firestore, collectionId)](./firestore_.md#collectiongroup) | Creates and returns a new Query instance that includes all documents in the database that are contained in a collection or subcollection with the given collectionId. | -| [connectFirestoreEmulator(firestore, host, port, options)](./firestore_.md#connectfirestoreemulator) | Modify this instance to communicate with the Cloud Firestore emulator.Note: This must be called before this instance has been used to do any operations. | -| [deleteDoc(reference)](./firestore_.md#deletedoc) | Deletes the document referred to by the specified DocumentReference. | -| [deleteField()](./firestore_.md#deletefield) | Returns a sentinel for use with [updateDoc()](./firestore_lite.md#updatedoc) or [setDoc()](./firestore_lite.md#setdoc) with {merge: true} to mark a field for deletion. | -| [disableNetwork(firestore)](./firestore_.md#disablenetwork) | Disables network usage for this instance. It can be re-enabled via [enableNetwork()](./firestore_.md#enablenetwork). While the network is disabled, any snapshot listeners, getDoc() or getDocs() calls will return results from cache, and any write operations will be queued until the network is restored. | -| [doc(firestore, path, pathSegments)](./firestore_.md#doc) | Gets a DocumentReference instance that refers to the document at the specified absolute path. | -| [doc(reference, path, pathSegments)](./firestore_.md#doc) | Gets a DocumentReference instance that refers to a document within reference at the specified relative path. If no path is specified, an automatically-generated unique ID will be used for the returned DocumentReference. | -| [doc(reference, path, pathSegments)](./firestore_.md#doc) | Gets a DocumentReference instance that refers to a document within reference at the specified relative path. | -| [documentId()](./firestore_.md#documentid) | Returns a special sentinel FieldPath to refer to the ID of a document. It can be used in queries to sort or filter by the document ID. | -| [enableIndexedDbPersistence(firestore, persistenceSettings)](./firestore_.md#enableindexeddbpersistence) | Attempts to enable persistent storage, if possible.Must be called before any other functions (other than [initializeFirestore()](./firestore_.md#initializefirestore), [getFirestore()](./firestore_.md#getfirestore) or [clearIndexedDbPersistence()](./firestore_.md#clearindexeddbpersistence).If this fails, enableIndexedDbPersistence() will reject the promise it returns. Note that even after this failure, the [Firestore](./firestore_.firestore.md#firestore_class) instance will remain usable, however offline persistence will be disabled.There are several reasons why this can fail, which can be identified by the code on the error.\* failed-precondition: The app is already open in another browser tab. \* unimplemented: The browser is incompatible with the offline persistence implementation. | -| [enableMultiTabIndexedDbPersistence(firestore)](./firestore_.md#enablemultitabindexeddbpersistence) | Attempts to enable multi-tab persistent storage, if possible. If enabled across all tabs, all operations share access to local persistence, including shared execution of queries and latency-compensated local document updates across all connected instances.If this fails, enableMultiTabIndexedDbPersistence() will reject the promise it returns. Note that even after this failure, the [Firestore](./firestore_.firestore.md#firestore_class) instance will remain usable, however offline persistence will be disabled.There are several reasons why this can fail, which can be identified by the code on the error.\* failed-precondition: The app is already open in another browser tab and multi-tab is not enabled. \* unimplemented: The browser is incompatible with the offline persistence implementation. | -| [enableNetwork(firestore)](./firestore_.md#enablenetwork) | Re-enables use of the network for this [Firestore](./firestore_.firestore.md#firestore_class) instance after a prior call to [disableNetwork()](./firestore_.md#disablenetwork). | -| [endAt(snapshot)](./firestore_.md#endat) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end at the provided document (inclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | -| [endAt(fieldValues)](./firestore_.md#endat) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | -| [endBefore(snapshot)](./firestore_.md#endbefore) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | -| [endBefore(fieldValues)](./firestore_.md#endbefore) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | -| [getCountFromServer(query)](./firestore_.md#getcountfromserver) | Calculates the number of documents in the result set of the given query, without actually downloading the documents.Using this function to count the documents is efficient because only the final count, not the documents' data, is downloaded. This function can even count the documents if the result set would be prohibitively large to download entirely (e.g. thousands of documents).The result received from the server is presented, unaltered, without considering any local state. That is, documents in the local cache are not taken into consideration, neither are local modifications not yet synchronized with the server. Previously-downloaded results, if any, are not used: every request using this source necessarily involves a round trip to the server. | -| [getDoc(reference)](./firestore_.md#getdoc) | Reads the document referred to by this DocumentReference.Note: getDoc() attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. To specify this behavior, invoke [getDocFromCache()](./firestore_.md#getdocfromcache) or [getDocFromServer()](./firestore_.md#getdocfromserver). | -| [getDocFromCache(reference)](./firestore_.md#getdocfromcache) | Reads the document referred to by this DocumentReference from cache. Returns an error if the document is not currently cached. | -| [getDocFromServer(reference)](./firestore_.md#getdocfromserver) | Reads the document referred to by this DocumentReference from the server. Returns an error if the network is not available. | -| [getDocs(query)](./firestore_.md#getdocs) | Executes the query and returns the results as a QuerySnapshot.Note: getDocs() attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. To specify this behavior, invoke [getDocsFromCache()](./firestore_.md#getdocsfromcache) or [getDocsFromServer()](./firestore_.md#getdocsfromserver). | -| [getDocsFromCache(query)](./firestore_.md#getdocsfromcache) | Executes the query and returns the results as a QuerySnapshot from cache. Returns an error if the document is not currently cached. | -| [getDocsFromServer(query)](./firestore_.md#getdocsfromserver) | Executes the query and returns the results as a QuerySnapshot from the server. Returns an error if the network is not available. | -| [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()](./firestore_.md#getfirestore) | Returns the existing default [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. | -| [increment(n)](./firestore_.md#increment) | 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 increment the field's current value by the given value.If either the operand or the current field value uses floating point precision, all arithmetic follows IEEE 754 semantics. If both values are integers, values outside of JavaScript's safe number range (Number.MIN_SAFE_INTEGER to Number.MAX_SAFE_INTEGER) are also subject to precision loss. Furthermore, once processed by the Firestore backend, all integer operations are capped between -2^63 and 2^63-1.If the current field value is not of type number, or if the field does not yet exist, the transformation sets the field to the given value. | -| [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). | -| [limit(limit)](./firestore_.md#limit) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that only returns the first matching documents. | -| [limitToLast(limit)](./firestore_.md#limittolast) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that only returns the last matching documents.You must specify at least one orderBy clause for limitToLast queries, otherwise an exception will be thrown during execution. | -| [loadBundle(firestore, bundleData)](./firestore_.md#loadbundle) | Loads a Firestore bundle into the local cache. | -| [namedQuery(firestore, name)](./firestore_.md#namedquery) | Reads a Firestore [Query](./firestore_.query.md#query_class) 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](./firestore_.query.md#query_class) by name. | -| [onSnapshot(reference, observer)](./firestore_.md#onsnapshot) | Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | -| [onSnapshot(reference, options, observer)](./firestore_.md#onsnapshot) | Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | -| [onSnapshot(reference, onNext, onError, onCompletion)](./firestore_.md#onsnapshot) | Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | -| [onSnapshot(reference, options, onNext, onError, onCompletion)](./firestore_.md#onsnapshot) | Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | -| [onSnapshot(query, observer)](./firestore_.md#onsnapshot) | Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | -| [onSnapshot(query, options, observer)](./firestore_.md#onsnapshot) | Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | -| [onSnapshot(query, onNext, onError, onCompletion)](./firestore_.md#onsnapshot) | Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | -| [onSnapshot(query, options, onNext, onError, onCompletion)](./firestore_.md#onsnapshot) | Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | -| [onSnapshotsInSync(firestore, observer)](./firestore_.md#onsnapshotsinsync) | Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners.NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use SnapshotMetadata in the individual listeners to determine if a snapshot is from the cache or the server. | -| [onSnapshotsInSync(firestore, onSync)](./firestore_.md#onsnapshotsinsync) | Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners.NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use SnapshotMetadata in the individual listeners to determine if a snapshot is from the cache or the server. | -| [orderBy(fieldPath, directionStr)](./firestore_.md#orderby) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that sorts the query result by the specified field, optionally in descending order instead of ascending. | -| [query(query, queryConstraints)](./firestore_.md#query) | Creates a new immutable instance of [Query](./firestore_.query.md#query_class) that is extended to also include additional query constraints. | -| [queryEqual(left, right)](./firestore_.md#queryequal) | Returns true if the provided queries point to the same collection and apply the same constraints. | -| [refEqual(left, right)](./firestore_.md#refequal) | Returns true if the provided references are equal. | -| [runTransaction(firestore, updateFunction, options)](./firestore_.md#runtransaction) | Executes the given updateFunction and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, Cloud Firestore retries the updateFunction. If it fails to commit after 5 attempts, the transaction fails.The maximum number of writes allowed in a single transaction is 500. | -| [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. | -| [setDoc(reference, data)](./firestore_.md#setdoc) | Writes to the document referred to by this DocumentReference. If the document does not yet exist, it will be created. | -| [setDoc(reference, data, options)](./firestore_.md#setdoc) | Writes to the document referred to by the specified DocumentReference. If the document does not yet exist, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document. | -| [setIndexConfiguration(firestore, configuration)](./firestore_.md#setindexconfiguration) | (BETA) Configures indexing for local query execution. Any previous index configuration is overridden. The Promise resolves once the index configuration has been persisted.The index entries themselves are created asynchronously. You can continue to use queries that require indexing even if the indices are not yet available. Query execution will automatically start using the index once the index entries have been written.Indexes are only supported with IndexedDb persistence. Invoke either enableIndexedDbPersistence() or enableMultiTabIndexedDbPersistence() before setting an index configuration. If IndexedDb is not enabled, any index configuration is ignored. | -| [setIndexConfiguration(firestore, json)](./firestore_.md#setindexconfiguration) | (BETA) Configures indexing for local query execution. Any previous index configuration is overridden. The Promise resolves once the index configuration has been persisted.The index entries themselves are created asynchronously. You can continue to use queries that require indexing even if the indices are not yet available. Query execution will automatically start using the index once the index entries have been written.Indexes are only supported with IndexedDb persistence. Invoke either enableIndexedDbPersistence() or enableMultiTabIndexedDbPersistence() before setting an index configuration. If IndexedDb is not enabled, any index configuration is ignored.The method accepts the JSON format exported by the Firebase CLI (firebase firestore:indexes). If the JSON format is invalid, this method throws an error. | -| [setLogLevel(logLevel)](./firestore_.md#setloglevel) | Sets the verbosity of Cloud Firestore logs (debug, error, or silent). | -| [snapshotEqual(left, right)](./firestore_.md#snapshotequal) | Returns true if the provided snapshots are equal. | -| [startAfter(snapshot)](./firestore_.md#startafter) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | -| [startAfter(fieldValues)](./firestore_.md#startafter) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | -| [startAt(snapshot)](./firestore_.md#startat) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of this query. | -| [startAt(fieldValues)](./firestore_.md#startat) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | -| [terminate(firestore)](./firestore_.md#terminate) | Terminates the provided [Firestore](./firestore_.firestore.md#firestore_class) instance.After calling terminate() only the clearIndexedDbPersistence() function may be used. Any other function will throw a FirestoreError.To restart after termination, create a new instance of FirebaseFirestore with [getFirestore()](./firestore_.md#getfirestore).Termination does not cancel any pending writes, and any promises that are awaiting a response from the server will not be resolved. If you have persistence enabled, the next time you start this instance, it will resume sending these writes to the server.Note: Under normal circumstances, calling terminate() is not required. This function is useful only when you want to force this instance to release all of its resources or in combination with clearIndexedDbPersistence() to ensure that all local state is destroyed between test runs. | -| [updateDoc(reference, data)](./firestore_.md#updatedoc) | Updates fields in the document referred to by the specified DocumentReference. The update will fail if applied to a document that does not exist. | -| [updateDoc(reference, field, value, moreFieldsAndValues)](./firestore_.md#updatedoc) | Updates fields in the document referred to by the specified DocumentReference The update will fail if applied to a document that does not exist.Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects. | -| [waitForPendingWrites(firestore)](./firestore_.md#waitforpendingwrites) | Waits until all currently pending writes for the active user have been acknowledged by the backend.The returned promise resolves immediately if there are no outstanding writes. Otherwise, the promise waits for all previously issued writes (including those written in a previous app session), but it does not wait for writes that were added after the function is called. If you want to wait for additional writes, call waitForPendingWrites() again.Any outstanding waitForPendingWrites() promises are rejected during user changes. | -| [where(fieldPath, opStr, value)](./firestore_.md#where) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that enforces that documents must contain the specified field and that the value should satisfy the relation constraint provided. | -| [writeBatch(firestore)](./firestore_.md#writebatch) | Creates a write batch, used for performing multiple writes as a single atomic operation. The maximum number of writes allowed in a single [WriteBatch](./firestore_.writebatch.md#writebatch_class) is 500.Unlike transactions, write batches are persisted offline and therefore are preferable when you don't need to condition your writes on read data. | - -## Classes - -| Class | Description | -| --- | --- | -| [AggregateField](./firestore_.aggregatefield.md#aggregatefield_class) | Represents an aggregation that can be performed by Firestore. | -| [AggregateQuerySnapshot](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshot_class) | The results of executing an aggregation query. | -| [Bytes](./firestore_.bytes.md#bytes_class) | An immutable object representing an array of bytes. | -| [CollectionReference](./firestore_.collectionreference.md#collectionreference_class) | A CollectionReference object can be used for adding documents, getting document references, and querying for documents (using [query()](./firestore_.md#query)). | -| [DocumentReference](./firestore_.documentreference.md#documentreference_class) | A DocumentReference refers to a document location in a Firestore database and can be used to write, read, or listen to the location. The document at the referenced location may or may not exist. | -| [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class) | A DocumentSnapshot contains data read from a document in your Firestore database. The data can be extracted with .data() or .get(<field>) to get a specific field.For a DocumentSnapshot that points to a non-existing document, any data access will return 'undefined'. You can use the exists() method to explicitly verify a document's existence. | -| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | A FieldPath refers to a field in a document. The path may consist of a single field name (referring to a top-level field in the document), or a list of field names (referring to a nested field in the document).Create a FieldPath by providing field names. If more than one field name is provided, the path will point to a nested field in a document. | -| [FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) | Sentinel values that can be used when writing document fields with set() or update(). | -| [Firestore](./firestore_.firestore.md#firestore_class) | The Cloud Firestore service interface.Do not call this constructor directly. Instead, use [getFirestore()](./firestore_.md#getfirestore). | -| [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class) | An error returned by a Firestore operation. | -| [GeoPoint](./firestore_.geopoint.md#geopoint_class) | An immutable object representing a geographic location in Firestore. The location is represented as latitude/longitude pair.Latitude values are in the range of \[-90, 90\]. Longitude values are in the range of \[-180, 180\]. | -| [LoadBundleTask](./firestore_.loadbundletask.md#loadbundletask_class) | 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>. | -| [Query](./firestore_.query.md#query_class) | A Query refers to a query which you can read or listen to. You can also construct refined Query objects by adding filters and ordering. | -| [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) | A QueryConstraint is used to narrow the set of documents returned by a Firestore query. QueryConstraints are created by invoking [where()](./firestore_.md#where), [orderBy()](./firestore_.md#orderby), [startAt()](./firestore_.md#startat), [startAfter()](./firestore_.md#startafter), , [endAt()](./firestore_.md#endat), [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryConstraint. | -| [QueryDocumentSnapshot](./firestore_.querydocumentsnapshot.md#querydocumentsnapshot_class) | A QueryDocumentSnapshot contains data read from a document in your Firestore database as part of a query. The document is guaranteed to exist and its data can be extracted with .data() or .get(<field>) to get a specific field.A QueryDocumentSnapshot offers the same API surface as a DocumentSnapshot. Since query results contain only existing documents, the exists property will always be true and data() will never return 'undefined'. | -| [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class) | A QuerySnapshot contains zero or more DocumentSnapshot objects representing the results of a query. The documents can be accessed as an array via the docs property or enumerated using the forEach method. The number of documents can be determined via the empty and size properties. | -| [SnapshotMetadata](./firestore_.snapshotmetadata.md#snapshotmetadata_class) | Metadata about a snapshot, describing the state of the snapshot. | -| [Timestamp](./firestore_.timestamp.md#timestamp_class) | A Timestamp represents a point in time independent of any time zone or calendar, represented as seconds and fractions of seconds at nanosecond resolution in UTC Epoch time.It is encoded using the Proleptic Gregorian Calendar which extends the Gregorian calendar backwards to year one. It is encoded assuming all minutes are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.For examples and further specifications, refer to the [Timestamp definition](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto). | -| [Transaction](./firestore_.transaction.md#transaction_class) | A reference to a transaction.The Transaction object passed to a transaction's updateFunction provides the methods to read and write data within the transaction context. See [runTransaction()](./firestore_.md#runtransaction). | -| [WriteBatch](./firestore_.writebatch.md#writebatch_class) | A write batch, used to perform multiple writes as a single atomic unit.A WriteBatch object can be acquired by calling [writeBatch()](./firestore_.md#writebatch). It provides methods for adding writes to the write batch. None of the writes will be committed (or visible locally) until [WriteBatch.commit()](./firestore_.writebatch.md#writebatchcommit) is called. | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [AggregateSpec](./firestore_.aggregatespec.md#aggregatespec_interface) | A type whose property values are all AggregateField objects. | -| [DocumentChange](./firestore_.documentchange.md#documentchange_interface) | A DocumentChange represents a change to the documents matching a query. It contains the document affected and the type of change that occurred. | -| [DocumentData](./firestore_.documentdata.md#documentdata_interface) | Document data (for use with [setDoc()](./firestore_lite.md#setdoc)) consists of fields mapped to values. | -| [FirestoreDataConverter](./firestore_.firestoredataconverter.md#firestoredataconverter_interface) | Converter used by withConverter() to transform user objects of type T into Firestore data.Using the converter allows you to specify generic type arguments when storing and retrieving objects from Firestore. | -| [FirestoreSettings](./firestore_.firestoresettings.md#firestoresettings_interface) | Specifies custom configurations for your Cloud Firestore instance. You must set these before invoking any other methods. | -| [Index](./firestore_.index.md#index_interface) | (BETA) The SDK definition of a Firestore index. | -| [IndexConfiguration](./firestore_.indexconfiguration.md#indexconfiguration_interface) | (BETA) A list of Firestore indexes to speed up local query execution.See [JSON Format](https://firebase.google.com/docs/reference/firestore/indexes/#json_format) for a description of the format of the index definition. | -| [IndexField](./firestore_.indexfield.md#indexfield_interface) | (BETA) A single field element in an index configuration. | -| [LoadBundleTaskProgress](./firestore_.loadbundletaskprogress.md#loadbundletaskprogress_interface) | Represents a progress update or a final state from loading bundles. | -| [PersistenceSettings](./firestore_.persistencesettings.md#persistencesettings_interface) | Settings that can be passed to enableIndexedDbPersistence() to configure Firestore persistence. | -| [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | An options object that can be passed to [onSnapshot()](./firestore_.md#onsnapshot) and [QuerySnapshot.docChanges()](./firestore_.querysnapshot.md#querysnapshotdocchanges) to control which types of changes to include in the result set. | -| [SnapshotOptions](./firestore_.snapshotoptions.md#snapshotoptions_interface) | Options that configure how data is retrieved from a DocumentSnapshot (for example the desired behavior for server timestamps that have not yet been set to their final value). | -| [TransactionOptions](./firestore_.transactionoptions.md#transactionoptions_interface) | Options to customize transaction behavior. | -| [Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) | A function returned by onSnapshot() that removes the listener when invoked. | - -## Variables - -| Variable | Description | -| --- | --- | -| [CACHE\_SIZE\_UNLIMITED](./firestore_.md#cache_size_unlimited) | Constant used to indicate the LRU garbage collection should be disabled. Set this value as the cacheSizeBytes on the settings passed to the [Firestore](./firestore_.firestore.md#firestore_class) instance. | - -## Type Aliases - -| Type Alias | Description | -| --- | --- | -| [AddPrefixToKeys](./firestore_.md#addprefixtokeys) | Returns a new map where every key is prefixed with the outer key appended to a dot. | -| [AggregateFieldType](./firestore_.md#aggregatefieldtype) | The union of all AggregateField types that are supported by Firestore. | -| [AggregateSpecData](./firestore_.md#aggregatespecdata) | A type whose keys are taken from an AggregateSpec, and whose values are the result of the aggregation performed by the corresponding AggregateField from the input AggregateSpec. | -| [ChildUpdateFields](./firestore_.md#childupdatefields) | Helper for calculating the nested fields for a given type T1. This is needed to distribute union types such as undefined | {...} (happens for optional props) or {a: A} | {b: B}.In this use case, V is used to distribute the union types of T[K] on Record, since T[K] is evaluated as an expression and not distributed.See https://www.typescriptlang.org/docs/handbook/advanced-types.html\#distributive-conditional-types | -| [DocumentChangeType](./firestore_.md#documentchangetype) | The type of a DocumentChange may be 'added', 'removed', or 'modified'. | -| [FirestoreErrorCode](./firestore_.md#firestoreerrorcode) | The set of Firestore status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.mdPossible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (e.g. an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation. | -| [NestedUpdateFields](./firestore_.md#nestedupdatefields) | For each field (e.g. 'bar'), find all nested keys (e.g. {'bar.baz': T1, 'bar.qux': T2}). Intersect them together to make a single map containing all possible keys that are all marked as optional | -| [OrderByDirection](./firestore_.md#orderbydirection) | The direction of a [orderBy()](./firestore_.md#orderby) clause is specified as 'desc' or 'asc' (descending or ascending). | -| [PartialWithFieldValue](./firestore_.md#partialwithfieldvalue) | Similar to Typescript's Partial<T>, but allows nested fields to be omitted and FieldValues to be passed in as property values. | -| [Primitive](./firestore_.md#primitive) | Primitive types. | -| [QueryConstraintType](./firestore_.md#queryconstrainttype) | Describes the different query constraints available in this SDK. | -| [SetOptions](./firestore_.md#setoptions) | An options object that configures the behavior of [setDoc()](./firestore_lite.md#setdoc), and calls. These calls can be configured to perform granular merges instead of overwriting the target documents in their entirety by providing a SetOptions with merge: true. | -| [TaskState](./firestore_.md#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. | -| [UnionToIntersection](./firestore_.md#uniontointersection) | Given a union type U = T1 | T2 | ..., returns an intersected type (T1 & T2 & ...).Uses distributive conditional types and inference from conditional types. This works because multiple candidates for the same type variable in contra-variant positions causes an intersection type to be inferred. https://www.typescriptlang.org/docs/handbook/advanced-types.html\#type-inference-in-conditional-types https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection-type | -| [UpdateData](./firestore_.md#updatedata) | Update data (for use with [updateDoc()](./firestore_.md#updatedoc)) that consists of field paths (e.g. 'foo' or 'foo.baz') mapped to values. Fields that contain dots reference nested fields within the document. FieldValues can be passed in as property values. | -| [WhereFilterOp](./firestore_.md#wherefilterop) | Filter conditions in a [where()](./firestore_.md#where) clause are specified using the strings '&lt;', '&lt;=', '==', '!=', '&gt;=', '&gt;', 'array-contains', 'in', 'array-contains-any', and 'not-in'. | -| [WithFieldValue](./firestore_.md#withfieldvalue) | Allows FieldValues to be passed in as a property value while maintaining type safety. | - -## addDoc() - -Add a new document to specified `CollectionReference` with the given data, assigning it a document ID automatically. - -Signature: - -```typescript -export declare function addDoc(reference: CollectionReference, data: WithFieldValue): Promise>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | A reference to the collection to add this document to. | -| data | [WithFieldValue](./firestore_.md#withfieldvalue)<T> | An Object containing the data for the new document. | - -Returns: - -Promise<[DocumentReference](./firestore_.documentreference.md#documentreference_class)<T>> - -A `Promise` resolved with a `DocumentReference` pointing to the newly created document after it has been written to the backend (Note that it won't resolve while you're offline). - -## aggregateQuerySnapshotEqual() - -Compares two `AggregateQuerySnapshot` instances for equality. - -Two `AggregateQuerySnapshot` instances are considered "equal" if they have underlying queries that compare equal, and the same data. - -Signature: - -```typescript -export declare function aggregateQuerySnapshotEqual(left: AggregateQuerySnapshot, right: AggregateQuerySnapshot): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| left | [AggregateQuerySnapshot](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<T> | The first AggregateQuerySnapshot to compare. | -| right | [AggregateQuerySnapshot](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<T> | The second AggregateQuerySnapshot to compare. | - -Returns: - -boolean - -`true` if the objects are "equal", as defined above, or `false` otherwise. - -## 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. - -Signature: - -```typescript -export declare function arrayRemove(...elements: unknown[]): FieldValue; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| elements | unknown\[\] | The elements to remove from the array. | - -Returns: - -[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) - -The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()` - -## 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. - -Signature: - -```typescript -export declare function arrayUnion(...elements: unknown[]): FieldValue; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| elements | unknown\[\] | The elements to union into the array. | - -Returns: - -[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) - -The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()`. - -## 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. - -Signature: - -```typescript -export declare function clearIndexedDbPersistence(firestore: Firestore): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to clear persistence for. | - -Returns: - -Promise<void> - -A `Promise` that is resolved when the persistent storage is cleared. Otherwise, the promise is rejected with an error. - -## collection() - -Gets a `CollectionReference` instance that refers to the collection at the specified absolute path. - -Signature: - -```typescript -export declare function collection(firestore: Firestore, path: string, ...pathSegments: string[]): CollectionReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | A reference to the root Firestore instance. | -| path | string | A slash-separated path to a collection. | -| pathSegments | string\[\] | Additional path segments to apply relative to the first argument. | - -Returns: - -[CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> - -The `CollectionReference` instance. - -## Exceptions - -If the final path has an even number of segments and does not point to a collection. - -## collection() - -Gets a `CollectionReference` instance that refers to a subcollection of `reference` at the the specified relative path. - -Signature: - -```typescript -export declare function collection(reference: CollectionReference, path: string, ...pathSegments: string[]): CollectionReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<unknown> | A reference to a collection. | -| path | string | A slash-separated path to a collection. | -| pathSegments | string\[\] | Additional path segments to apply relative to the first argument. | - -Returns: - -[CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> - -The `CollectionReference` instance. - -## Exceptions - -If the final path has an even number of segments and does not point to a collection. - -## collection() - -Gets a `CollectionReference` instance that refers to a subcollection of `reference` at the the specified relative path. - -Signature: - -```typescript -export declare function collection(reference: DocumentReference, path: string, ...pathSegments: string[]): CollectionReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class) | A reference to a Firestore document. | -| path | string | A slash-separated path to a collection. | -| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | - -Returns: - -[CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> - -The `CollectionReference` instance. - -## Exceptions - -If the final path has an even number of segments and does not point to a collection. - -## collectionGroup() - -Creates and returns a new `Query` instance that includes all documents in the database that are contained in a collection or subcollection with the given `collectionId`. - -Signature: - -```typescript -export declare function collectionGroup(firestore: Firestore, collectionId: string): Query; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | A reference to the root Firestore instance. | -| collectionId | string | Identifies the collections to query over. Every collection or subcollection with this ID as the last segment of its path will be included. Cannot contain a slash. | - -Returns: - -[Query](./firestore_.query.md#query_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> - -The created `Query`. - -## connectFirestoreEmulator() - -Modify this instance to communicate with the Cloud Firestore emulator. - -Note: This must be called before this instance has been used to do any operations. - -Signature: - -```typescript -export declare function connectFirestoreEmulator(firestore: Firestore, host: string, port: number, options?: { - mockUserToken?: EmulatorMockTokenOptions | string; -}): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The Firestore instance to configure to connect to the emulator. | -| host | string | the emulator host (ex: localhost). | -| port | number | the emulator port (ex: 9000). | -| options | { mockUserToken?: [EmulatorMockTokenOptions](./util.md#emulatormocktokenoptions) \| string; } | | - -Returns: - -void - -## deleteDoc() - -Deletes the document referred to by the specified `DocumentReference`. - -Signature: - -```typescript -export declare function deleteDoc(reference: DocumentReference): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to the document to delete. | - -Returns: - -Promise<void> - -A Promise resolved once the document has been successfully deleted from the backend (note that it won't resolve while you're offline). - -## deleteField() - -Returns a sentinel for use with [updateDoc()](./firestore_lite.md#updatedoc) or [setDoc()](./firestore_lite.md#setdoc) with `{merge: true}` to mark a field for deletion. - -Signature: - -```typescript -export declare function deleteField(): FieldValue; -``` -Returns: - -[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) - -## disableNetwork() - -Disables network usage for this instance. It can be re-enabled via [enableNetwork()](./firestore_.md#enablenetwork). While the network is disabled, any snapshot listeners, `getDoc()` or `getDocs()` calls will return results from cache, and any write operations will be queued until the network is restored. - -Signature: - -```typescript -export declare function disableNetwork(firestore: Firestore): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | - -Returns: - -Promise<void> - -A `Promise` that is resolved once the network has been disabled. - -## doc() - -Gets a `DocumentReference` instance that refers to the document at the specified absolute path. - -Signature: - -```typescript -export declare function doc(firestore: Firestore, path: string, ...pathSegments: string[]): DocumentReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | A reference to the root Firestore instance. | -| path | string | A slash-separated path to a document. | -| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | - -Returns: - -[DocumentReference](./firestore_.documentreference.md#documentreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> - -The `DocumentReference` instance. - -## Exceptions - -If the final path has an odd number of segments and does not point to a document. - -## doc() - -Gets a `DocumentReference` instance that refers to a document within `reference` at the specified relative path. If no path is specified, an automatically-generated unique ID will be used for the returned `DocumentReference`. - -Signature: - -```typescript -export declare function doc(reference: CollectionReference, path?: string, ...pathSegments: string[]): DocumentReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | A reference to a collection. | -| path | string | A slash-separated path to a document. Has to be omitted to use auto-genrated IDs. | -| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | - -Returns: - -[DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> - -The `DocumentReference` instance. - -## Exceptions - -If the final path has an odd number of segments and does not point to a document. - -## doc() - -Gets a `DocumentReference` instance that refers to a document within `reference` at the specified relative path. - -Signature: - -```typescript -export declare function doc(reference: DocumentReference, path: string, ...pathSegments: string[]): DocumentReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to a Firestore document. | -| path | string | A slash-separated path to a document. | -| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | - -Returns: - -[DocumentReference](./firestore_.documentreference.md#documentreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> - -The `DocumentReference` instance. - -## Exceptions - -If the final path has an odd number of segments and does not point to a document. - -## documentId() - -Returns a special sentinel `FieldPath` to refer to the ID of a document. It can be used in queries to sort or filter by the document ID. - -Signature: - -```typescript -export declare function documentId(): FieldPath; -``` -Returns: - -[FieldPath](./firestore_.fieldpath.md#fieldpath_class) - -## enableIndexedDbPersistence() - -Attempts to enable persistent storage, if possible. - -Must be called before any other functions (other than [initializeFirestore()](./firestore_.md#initializefirestore), [getFirestore()](./firestore_.md#getfirestore) or [clearIndexedDbPersistence()](./firestore_.md#clearindexeddbpersistence). - -If this fails, `enableIndexedDbPersistence()` will reject the promise it returns. Note that even after this failure, the [Firestore](./firestore_.firestore.md#firestore_class) instance will remain usable, however offline persistence will be disabled. - -There are several reasons why this can fail, which can be identified by the `code` on the error. - -\* failed-precondition: The app is already open in another browser tab. \* unimplemented: The browser is incompatible with the offline persistence implementation. - -Signature: - -```typescript -export declare function enableIndexedDbPersistence(firestore: Firestore, persistenceSettings?: PersistenceSettings): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to enable persistence for. | -| persistenceSettings | [PersistenceSettings](./firestore_.persistencesettings.md#persistencesettings_interface) | Optional settings object to configure persistence. | - -Returns: - -Promise<void> - -A `Promise` that represents successfully enabling persistent storage. - -## enableMultiTabIndexedDbPersistence() - -Attempts to enable multi-tab persistent storage, if possible. If enabled across all tabs, all operations share access to local persistence, including shared execution of queries and latency-compensated local document updates across all connected instances. - -If this fails, `enableMultiTabIndexedDbPersistence()` will reject the promise it returns. Note that even after this failure, the [Firestore](./firestore_.firestore.md#firestore_class) instance will remain usable, however offline persistence will be disabled. - -There are several reasons why this can fail, which can be identified by the `code` on the error. - -\* failed-precondition: The app is already open in another browser tab and multi-tab is not enabled. \* unimplemented: The browser is incompatible with the offline persistence implementation. - -Signature: - -```typescript -export declare function enableMultiTabIndexedDbPersistence(firestore: Firestore): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to enable persistence for. | - -Returns: - -Promise<void> - -A `Promise` that represents successfully enabling persistent storage. - -## enableNetwork() - -Re-enables use of the network for this [Firestore](./firestore_.firestore.md#firestore_class) instance after a prior call to [disableNetwork()](./firestore_.md#disablenetwork). - -Signature: - -```typescript -export declare function enableNetwork(firestore: Firestore): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | - -Returns: - -Promise<void> - -A `Promise` that is resolved once the network has been enabled. - -## endAt() - -Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end at the provided document (inclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. - -Signature: - -```typescript -export declare function endAt(snapshot: DocumentSnapshot): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| snapshot | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to end at. | - -Returns: - -[QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) - -A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()` - -## endAt() - -Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. - -Signature: - -```typescript -export declare function endAt(...fieldValues: unknown[]): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldValues | unknown\[\] | The field values to end this query at, in order of the query's order by. | - -Returns: - -[QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) - -A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()` - -## endBefore() - -Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. - -Signature: - -```typescript -export declare function endBefore(snapshot: DocumentSnapshot): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| snapshot | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to end before. | - -Returns: - -[QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) - -A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()` - -## endBefore() - -Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. - -Signature: - -```typescript -export declare function endBefore(...fieldValues: unknown[]): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldValues | unknown\[\] | The field values to end this query before, in order of the query's order by. | - -Returns: - -[QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) - -A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()` - -## getCountFromServer() - -Calculates the number of documents in the result set of the given query, without actually downloading the documents. - -Using this function to count the documents is efficient because only the final count, not the documents' data, is downloaded. This function can even count the documents if the result set would be prohibitively large to download entirely (e.g. thousands of documents). - -The result received from the server is presented, unaltered, without considering any local state. That is, documents in the local cache are not taken into consideration, neither are local modifications not yet synchronized with the server. Previously-downloaded results, if any, are not used: every request using this source necessarily involves a round trip to the server. - -Signature: - -```typescript -export declare function getCountFromServer(query: Query): Promise; -}>>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./firestore_.query.md#query_class)<unknown> | The query whose result set size to calculate. | - -Returns: - -Promise<[AggregateQuerySnapshot](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<{ count: [AggregateField](./firestore_.aggregatefield.md#aggregatefield_class)<number>; }>> - -A Promise that will be resolved with the count; the count can be retrieved from `snapshot.data().count`, where `snapshot` is the `AggregateQuerySnapshot` to which the returned Promise resolves. - -## getDoc() - -Reads the document referred to by this `DocumentReference`. - -Note: `getDoc()` attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. To specify this behavior, invoke [getDocFromCache()](./firestore_.md#getdocfromcache) or [getDocFromServer()](./firestore_.md#getdocfromserver). - -Signature: - -```typescript -export declare function getDoc(reference: DocumentReference): Promise>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | The reference of the document to fetch. | - -Returns: - -Promise<[DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>> - -A Promise resolved with a `DocumentSnapshot` containing the current document contents. - -## getDocFromCache() - -Reads the document referred to by this `DocumentReference` from cache. Returns an error if the document is not currently cached. - -Signature: - -```typescript -export declare function getDocFromCache(reference: DocumentReference): Promise>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | | - -Returns: - -Promise<[DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>> - -A `Promise` resolved with a `DocumentSnapshot` containing the current document contents. - -## getDocFromServer() - -Reads the document referred to by this `DocumentReference` from the server. Returns an error if the network is not available. - -Signature: - -```typescript -export declare function getDocFromServer(reference: DocumentReference): Promise>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | | - -Returns: - -Promise<[DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>> - -A `Promise` resolved with a `DocumentSnapshot` containing the current document contents. - -## getDocs() - -Executes the query and returns the results as a `QuerySnapshot`. - -Note: `getDocs()` attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. To specify this behavior, invoke [getDocsFromCache()](./firestore_.md#getdocsfromcache) or [getDocsFromServer()](./firestore_.md#getdocsfromserver). - -Signature: - -```typescript -export declare function getDocs(query: Query): Promise>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./firestore_.query.md#query_class)<T> | | - -Returns: - -Promise<[QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>> - -A `Promise` that will be resolved with the results of the query. - -## getDocsFromCache() - -Executes the query and returns the results as a `QuerySnapshot` from cache. Returns an error if the document is not currently cached. - -Signature: - -```typescript -export declare function getDocsFromCache(query: Query): Promise>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./firestore_.query.md#query_class)<T> | | - -Returns: - -Promise<[QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>> - -A `Promise` that will be resolved with the results of the query. - -## getDocsFromServer() - -Executes the query and returns the results as a `QuerySnapshot` from the server. Returns an error if the network is not available. - -Signature: - -```typescript -export declare function getDocsFromServer(query: Query): Promise>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./firestore_.query.md#query_class)<T> | | - -Returns: - -Promise<[QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>> - -A `Promise` that will be resolved with the results of the query. - -## 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. - -Signature: - -```typescript -export declare function getFirestore(app: FirebaseApp): Firestore; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance that the returned [Firestore](./firestore_.firestore.md#firestore_class) instance is associated with. | - -Returns: - -[Firestore](./firestore_.firestore.md#firestore_class) - -The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. - -## getFirestore() - -Returns the existing default [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: - -```typescript -export declare function getFirestore(): Firestore; -``` -Returns: - -[Firestore](./firestore_.firestore.md#firestore_class) - -The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. - -## increment() - -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 increment the field's current value by the given value. - -If either the operand or the current field value uses floating point precision, all arithmetic follows IEEE 754 semantics. If both values are integers, values outside of JavaScript's safe number range (`Number.MIN_SAFE_INTEGER` to `Number.MAX_SAFE_INTEGER`) are also subject to precision loss. Furthermore, once processed by the Firestore backend, all integer operations are capped between -2^63 and 2^63-1. - -If the current field value is not of type `number`, or if the field does not yet exist, the transformation sets the field to the given value. - -Signature: - -```typescript -export declare function increment(n: number): FieldValue; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| n | number | The value to increment by. | - -Returns: - -[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) - -The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()` - -## 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). - -Signature: - -```typescript -export declare function initializeFirestore(app: FirebaseApp, settings: FirestoreSettings, databaseId?: string): Firestore; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) with which the [Firestore](./firestore_.firestore.md#firestore_class) instance will be associated. | -| settings | [FirestoreSettings](./firestore_.firestoresettings.md#firestoresettings_interface) | A settings object to configure the [Firestore](./firestore_.firestore.md#firestore_class) instance. | -| databaseId | string | The name of database. | - -Returns: - -[Firestore](./firestore_.firestore.md#firestore_class) - -A newly initialized [Firestore](./firestore_.firestore.md#firestore_class) instance. - -## limit() - -Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that only returns the first matching documents. - -Signature: - -```typescript -export declare function limit(limit: number): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| limit | number | The maximum number of items to return. | - -Returns: - -[QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) - -The created [Query](./firestore_.query.md#query_class). - -## limitToLast() - -Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that only returns the last matching documents. - -You must specify at least one `orderBy` clause for `limitToLast` queries, otherwise an exception will be thrown during execution. - -Signature: - -```typescript -export declare function limitToLast(limit: number): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| limit | number | The maximum number of items to return. | - -Returns: - -[QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) - -The created [Query](./firestore_.query.md#query_class). - -## loadBundle() - -Loads a Firestore bundle into the local cache. - -Signature: - -```typescript -export declare function loadBundle(firestore: Firestore, bundleData: ReadableStream | ArrayBuffer | string): LoadBundleTask; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to load bundles for. | -| bundleData | ReadableStream<Uint8Array> \| ArrayBuffer \| string | An object representing the bundle to be loaded. Valid objects are ArrayBuffer, ReadableStream<Uint8Array> or string. | - -Returns: - -[LoadBundleTask](./firestore_.loadbundletask.md#loadbundletask_class) - -A `LoadBundleTask` object, which notifies callers with progress updates, and completion or error events. It can be used as a `Promise`. - -## namedQuery() - -Reads a Firestore [Query](./firestore_.query.md#query_class) 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](./firestore_.query.md#query_class) by name. - -Signature: - -```typescript -export declare function namedQuery(firestore: Firestore, name: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to read the query from. | -| name | string | The name of the query. | - -Returns: - -Promise<[Query](./firestore_.query.md#query_class) \| null> - -A `Promise` that is resolved with the Query or `null`. - -## onSnapshot() - -Attaches a listener for `DocumentSnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. - -NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. - -Signature: - -```typescript -export declare function onSnapshot(reference: DocumentReference, observer: { - next?: (snapshot: DocumentSnapshot) => void; - error?: (error: FirestoreError) => void; - complete?: () => void; -}): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to listen to. | -| observer | { next?: (snapshot: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>) => void; error?: (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void; complete?: () => void; } | A single object containing next and error callbacks. | - -Returns: - -[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) - -An unsubscribe function that can be called to cancel the snapshot listener. - -## onSnapshot() - -Attaches a listener for `DocumentSnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. - -NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. - -Signature: - -```typescript -export declare function onSnapshot(reference: DocumentReference, options: SnapshotListenOptions, observer: { - next?: (snapshot: DocumentSnapshot) => void; - error?: (error: FirestoreError) => void; - complete?: () => void; -}): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to listen to. | -| options | [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | Options controlling the listen behavior. | -| observer | { next?: (snapshot: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>) => void; error?: (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void; complete?: () => void; } | A single object containing next and error callbacks. | - -Returns: - -[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) - -An unsubscribe function that can be called to cancel the snapshot listener. - -## onSnapshot() - -Attaches a listener for `DocumentSnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. - -NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. - -Signature: - -```typescript -export declare function onSnapshot(reference: DocumentReference, onNext: (snapshot: DocumentSnapshot) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to listen to. | -| onNext | (snapshot: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>) => void | A callback to be called every time a new DocumentSnapshot is available. | -| onError | (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void | A callback to be called if the listen fails or is cancelled. No further callbacks will occur. | -| onCompletion | () => void | Can be provided, but will not be called since streams are never ending. | - -Returns: - -[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) - -An unsubscribe function that can be called to cancel the snapshot listener. - -## onSnapshot() - -Attaches a listener for `DocumentSnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. - -NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. - -Signature: - -```typescript -export declare function onSnapshot(reference: DocumentReference, options: SnapshotListenOptions, onNext: (snapshot: DocumentSnapshot) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to listen to. | -| options | [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | Options controlling the listen behavior. | -| onNext | (snapshot: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>) => void | A callback to be called every time a new DocumentSnapshot is available. | -| onError | (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void | A callback to be called if the listen fails or is cancelled. No further callbacks will occur. | -| onCompletion | () => void | Can be provided, but will not be called since streams are never ending. | - -Returns: - -[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) - -An unsubscribe function that can be called to cancel the snapshot listener. - -## onSnapshot() - -Attaches a listener for `QuerySnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. The listener can be cancelled by calling the function that is returned when `onSnapshot` is called. - -NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. - -Signature: - -```typescript -export declare function onSnapshot(query: Query, observer: { - next?: (snapshot: QuerySnapshot) => void; - error?: (error: FirestoreError) => void; - complete?: () => void; -}): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./firestore_.query.md#query_class)<T> | The query to listen to. | -| observer | { next?: (snapshot: [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>) => void; error?: (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void; complete?: () => void; } | A single object containing next and error callbacks. | - -Returns: - -[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) - -An unsubscribe function that can be called to cancel the snapshot listener. - -## onSnapshot() - -Attaches a listener for `QuerySnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. The listener can be cancelled by calling the function that is returned when `onSnapshot` is called. - -NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. - -Signature: - -```typescript -export declare function onSnapshot(query: Query, options: SnapshotListenOptions, observer: { - next?: (snapshot: QuerySnapshot) => void; - error?: (error: FirestoreError) => void; - complete?: () => void; -}): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./firestore_.query.md#query_class)<T> | The query to listen to. | -| options | [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | Options controlling the listen behavior. | -| observer | { next?: (snapshot: [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>) => void; error?: (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void; complete?: () => void; } | A single object containing next and error callbacks. | - -Returns: - -[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) - -An unsubscribe function that can be called to cancel the snapshot listener. - -## onSnapshot() - -Attaches a listener for `QuerySnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. The listener can be cancelled by calling the function that is returned when `onSnapshot` is called. - -NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. - -Signature: - -```typescript -export declare function onSnapshot(query: Query, onNext: (snapshot: QuerySnapshot) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./firestore_.query.md#query_class)<T> | The query to listen to. | -| onNext | (snapshot: [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>) => void | A callback to be called every time a new QuerySnapshot is available. | -| onError | (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void | A callback to be called if the listen fails or is cancelled. No further callbacks will occur. | -| onCompletion | () => void | Can be provided, but will not be called since streams are never ending. | - -Returns: - -[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) - -An unsubscribe function that can be called to cancel the snapshot listener. - -## onSnapshot() - -Attaches a listener for `QuerySnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. The listener can be cancelled by calling the function that is returned when `onSnapshot` is called. - -NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. - -Signature: - -```typescript -export declare function onSnapshot(query: Query, options: SnapshotListenOptions, onNext: (snapshot: QuerySnapshot) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./firestore_.query.md#query_class)<T> | The query to listen to. | -| options | [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | Options controlling the listen behavior. | -| onNext | (snapshot: [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>) => void | A callback to be called every time a new QuerySnapshot is available. | -| onError | (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void | A callback to be called if the listen fails or is cancelled. No further callbacks will occur. | -| onCompletion | () => void | Can be provided, but will not be called since streams are never ending. | - -Returns: - -[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) - -An unsubscribe function that can be called to cancel the snapshot listener. - -## onSnapshotsInSync() - -Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners. - -NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use SnapshotMetadata in the individual listeners to determine if a snapshot is from the cache or the server. - -Signature: - -```typescript -export declare function onSnapshotsInSync(firestore: Firestore, observer: { - next?: (value: void) => void; - error?: (error: FirestoreError) => void; - complete?: () => void; -}): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The instance of Firestore for synchronizing snapshots. | -| observer | { next?: (value: void) => void; error?: (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void; complete?: () => void; } | A single object containing next and error callbacks. | - -Returns: - -[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) - -An unsubscribe function that can be called to cancel the snapshot listener. - -## onSnapshotsInSync() - -Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners. - -NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use `SnapshotMetadata` in the individual listeners to determine if a snapshot is from the cache or the server. - -Signature: - -```typescript -export declare function onSnapshotsInSync(firestore: Firestore, onSync: () => void): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The Firestore instance for synchronizing snapshots. | -| onSync | () => void | A callback to be called every time all snapshot listeners are in sync with each other. | - -Returns: - -[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) - -An unsubscribe function that can be called to cancel the snapshot listener. - -## orderBy() - -Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that sorts the query result by the specified field, optionally in descending order instead of ascending. - -Signature: - -```typescript -export declare function orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDirection): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldPath | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The field to sort by. | -| directionStr | [OrderByDirection](./firestore_.md#orderbydirection) | Optional direction to sort by ('asc' or 'desc'). If not specified, order will be ascending. | - -Returns: - -[QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) - -The created [Query](./firestore_.query.md#query_class). - -## query() - -Creates a new immutable instance of [Query](./firestore_.query.md#query_class) that is extended to also include additional query constraints. - -Signature: - -```typescript -export declare function query(query: Query, ...queryConstraints: QueryConstraint[]): Query; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./firestore_.query.md#query_class)<T> | The [Query](./firestore_.query.md#query_class) instance to use as a base for the new constraints. | -| queryConstraints | [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class)\[\] | The list of [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class)s to apply. | - -Returns: - -[Query](./firestore_.query.md#query_class)<T> - -## Exceptions - -if any of the provided query constraints cannot be combined with the existing or new constraints. - -## queryEqual() - -Returns true if the provided queries point to the same collection and apply the same constraints. - -Signature: - -```typescript -export declare function queryEqual(left: Query, right: Query): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| left | [Query](./firestore_.query.md#query_class)<T> | A Query to compare. | -| right | [Query](./firestore_.query.md#query_class)<T> | A Query to compare. | - -Returns: - -boolean - -true if the references point to the same location in the same Firestore database. - -## refEqual() - -Returns true if the provided references are equal. - -Signature: - -```typescript -export declare function refEqual(left: DocumentReference | CollectionReference, right: DocumentReference | CollectionReference): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| left | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> \| [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | A reference to compare. | -| right | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> \| [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | A reference to compare. | - -Returns: - -boolean - -true if the references point to the same location in the same Firestore database. - -## runTransaction() - -Executes the given `updateFunction` and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, Cloud Firestore retries the `updateFunction`. If it fails to commit after 5 attempts, the transaction fails. - -The maximum number of writes allowed in a single transaction is 500. - -Signature: - -```typescript -export declare function runTransaction(firestore: Firestore, updateFunction: (transaction: Transaction) => Promise, options?: TransactionOptions): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | A reference to the Firestore database to run this transaction against. | -| updateFunction | (transaction: [Transaction](./firestore_.transaction.md#transaction_class)) => Promise<T> | The function to execute within the transaction context. | -| options | [TransactionOptions](./firestore_.transactionoptions.md#transactionoptions_interface) | An options object to configure maximum number of attempts to commit. | - -Returns: - -Promise<T> - -If the transaction completed successfully or was explicitly aborted (the `updateFunction` returned a failed promise), the promise returned by the `updateFunction `is returned here. Otherwise, if the transaction failed, a rejected promise with the corresponding failure error is returned. - -## 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. - -Signature: - -```typescript -export declare function serverTimestamp(): FieldValue; -``` -Returns: - -[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) - -## setDoc() - -Writes to the document referred to by this `DocumentReference`. If the document does not yet exist, it will be created. - -Signature: - -```typescript -export declare function setDoc(reference: DocumentReference, data: WithFieldValue): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to write. | -| data | [WithFieldValue](./firestore_.md#withfieldvalue)<T> | A map of the fields and values for the document. | - -Returns: - -Promise<void> - -A `Promise` resolved once the data has been successfully written to the backend (note that it won't resolve while you're offline). - -## setDoc() - -Writes to the document referred to by the specified `DocumentReference`. If the document does not yet exist, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. - -Signature: - -```typescript -export declare function setDoc(reference: DocumentReference, data: PartialWithFieldValue, options: SetOptions): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to write. | -| data | [PartialWithFieldValue](./firestore_.md#partialwithfieldvalue)<T> | A map of the fields and values for the document. | -| options | [SetOptions](./firestore_.md#setoptions) | An object to configure the set behavior. | - -Returns: - -Promise<void> - -A Promise resolved once the data has been successfully written to the backend (note that it won't resolve while you're offline). - -## setIndexConfiguration() - -> 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. -> - -Configures indexing for local query execution. Any previous index configuration is overridden. The `Promise` resolves once the index configuration has been persisted. - -The index entries themselves are created asynchronously. You can continue to use queries that require indexing even if the indices are not yet available. Query execution will automatically start using the index once the index entries have been written. - -Indexes are only supported with IndexedDb persistence. Invoke either `enableIndexedDbPersistence()` or `enableMultiTabIndexedDbPersistence()` before setting an index configuration. If IndexedDb is not enabled, any index configuration is ignored. - -Signature: - -```typescript -export declare function setIndexConfiguration(firestore: Firestore, configuration: IndexConfiguration): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to configure indexes for. | -| configuration | [IndexConfiguration](./firestore_.indexconfiguration.md#indexconfiguration_interface) | The index definition. | - -Returns: - -Promise<void> - -A `Promise` that resolves once all indices are successfully configured. - -## Exceptions - -FirestoreError if the JSON format is invalid. - -## setIndexConfiguration() - -> 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. -> - -Configures indexing for local query execution. Any previous index configuration is overridden. The `Promise` resolves once the index configuration has been persisted. - -The index entries themselves are created asynchronously. You can continue to use queries that require indexing even if the indices are not yet available. Query execution will automatically start using the index once the index entries have been written. - -Indexes are only supported with IndexedDb persistence. Invoke either `enableIndexedDbPersistence()` or `enableMultiTabIndexedDbPersistence()` before setting an index configuration. If IndexedDb is not enabled, any index configuration is ignored. - -The method accepts the JSON format exported by the Firebase CLI (`firebase firestore:indexes`). If the JSON format is invalid, this method throws an error. - -Signature: - -```typescript -export declare function setIndexConfiguration(firestore: Firestore, json: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to configure indexes for. | -| json | string | The JSON format exported by the Firebase CLI. | - -Returns: - -Promise<void> - -A `Promise` that resolves once all indices are successfully configured. - -## Exceptions - -FirestoreError if the JSON format is invalid. - -## setLogLevel() - -Sets the verbosity of Cloud Firestore logs (debug, error, or silent). - -Signature: - -```typescript -export declare function setLogLevel(logLevel: LogLevel): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| logLevel | LogLevel | The verbosity you set for activity and error logging. Can be any of the following values:

  • debug for the most verbose logging level, primarily for debugging.
  • error to log errors only.
  • silent to turn off logging.
| - -Returns: - -void - -## snapshotEqual() - -Returns true if the provided snapshots are equal. - -Signature: - -```typescript -export declare function snapshotEqual(left: DocumentSnapshot | QuerySnapshot, right: DocumentSnapshot | QuerySnapshot): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| left | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T> \| [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T> | A snapshot to compare. | -| right | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T> \| [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T> | A snapshot to compare. | - -Returns: - -boolean - -true if the snapshots are equal. - -## startAfter() - -Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. - -Signature: - -```typescript -export declare function startAfter(snapshot: DocumentSnapshot): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| snapshot | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to start after. | - -Returns: - -[QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) - -A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()` - -## startAfter() - -Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. - -Signature: - -```typescript -export declare function startAfter(...fieldValues: unknown[]): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldValues | unknown\[\] | The field values to start this query after, in order of the query's order by. | - -Returns: - -[QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) - -A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()` - -## startAt() - -Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the `orderBy` of this query. - -Signature: - -```typescript -export declare function startAt(snapshot: DocumentSnapshot): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| snapshot | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to start at. | - -Returns: - -[QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) - -A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()`. - -## startAt() - -Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. - -Signature: - -```typescript -export declare function startAt(...fieldValues: unknown[]): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldValues | unknown\[\] | The field values to start this query at, in order of the query's order by. | - -Returns: - -[QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) - -A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()`. - -## terminate() - -Terminates the provided [Firestore](./firestore_.firestore.md#firestore_class) instance. - -After calling `terminate()` only the `clearIndexedDbPersistence()` function may be used. Any other function will throw a `FirestoreError`. - -To restart after termination, create a new instance of FirebaseFirestore with [getFirestore()](./firestore_.md#getfirestore). - -Termination does not cancel any pending writes, and any promises that are awaiting a response from the server will not be resolved. If you have persistence enabled, the next time you start this instance, it will resume sending these writes to the server. - -Note: Under normal circumstances, calling `terminate()` is not required. This function is useful only when you want to force this instance to release all of its resources or in combination with `clearIndexedDbPersistence()` to ensure that all local state is destroyed between test runs. - -Signature: - -```typescript -export declare function terminate(firestore: Firestore): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | - -Returns: - -Promise<void> - -A `Promise` that is resolved when the instance has been successfully terminated. - -## updateDoc() - -Updates fields in the document referred to by the specified `DocumentReference`. The update will fail if applied to a document that does not exist. - -Signature: - -```typescript -export declare function updateDoc(reference: DocumentReference, data: UpdateData): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to update. | -| data | [UpdateData](./firestore_.md#updatedata)<T> | An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document. | - -Returns: - -Promise<void> - -A `Promise` resolved once the data has been successfully written to the backend (note that it won't resolve while you're offline). - -## updateDoc() - -Updates fields in the document referred to by the specified `DocumentReference` The update will fail if applied to a document that does not exist. - -Nested fields can be updated by providing dot-separated field path strings or by providing `FieldPath` objects. - -Signature: - -```typescript -export declare function updateDoc(reference: DocumentReference, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to the document to update. | -| field | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The first field to update. | -| value | unknown | The first value. | -| moreFieldsAndValues | unknown\[\] | Additional key value pairs. | - -Returns: - -Promise<void> - -A `Promise` resolved once the data has been successfully written to the backend (note that it won't resolve while you're offline). - -## waitForPendingWrites() - -Waits until all currently pending writes for the active user have been acknowledged by the backend. - -The returned promise resolves immediately if there are no outstanding writes. Otherwise, the promise waits for all previously issued writes (including those written in a previous app session), but it does not wait for writes that were added after the function is called. If you want to wait for additional writes, call `waitForPendingWrites()` again. - -Any outstanding `waitForPendingWrites()` promises are rejected during user changes. - -Signature: - -```typescript -export declare function waitForPendingWrites(firestore: Firestore): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | - -Returns: - -Promise<void> - -A `Promise` which resolves when all currently pending writes have been acknowledged by the backend. - -## where() - -Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that enforces that documents must contain the specified field and that the value should satisfy the relation constraint provided. - -Signature: - -```typescript -export declare function where(fieldPath: string | FieldPath, opStr: WhereFilterOp, value: unknown): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldPath | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The path to compare | -| opStr | [WhereFilterOp](./firestore_.md#wherefilterop) | The operation string (e.g "&lt;", "&lt;=", "==", "&lt;", "&lt;=", "!="). | -| value | unknown | The value for comparison | - -Returns: - -[QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) - -The created [Query](./firestore_.query.md#query_class). - -## writeBatch() - -Creates a write batch, used for performing multiple writes as a single atomic operation. The maximum number of writes allowed in a single [WriteBatch](./firestore_.writebatch.md#writebatch_class) is 500. - -Unlike transactions, write batches are persisted offline and therefore are preferable when you don't need to condition your writes on read data. - -Signature: - -```typescript -export declare function writeBatch(firestore: Firestore): WriteBatch; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | - -Returns: - -[WriteBatch](./firestore_.writebatch.md#writebatch_class) - -A [WriteBatch](./firestore_.writebatch.md#writebatch_class) that can be used to atomically execute multiple writes. - -## CACHE\_SIZE\_UNLIMITED - -Constant used to indicate the LRU garbage collection should be disabled. Set this value as the `cacheSizeBytes` on the settings passed to the [Firestore](./firestore_.firestore.md#firestore_class) instance. - -Signature: - -```typescript -CACHE_SIZE_UNLIMITED = -1 -``` - -## AddPrefixToKeys - -Returns a new map where every key is prefixed with the outer key appended to a dot. - -Signature: - -```typescript -export declare type AddPrefixToKeys> = { - [K in keyof T & string as `${Prefix}.${K}`]+?: T[K]; -}; -``` - -## AggregateFieldType - -The union of all `AggregateField` types that are supported by Firestore. - -Signature: - -```typescript -export declare type AggregateFieldType = AggregateField; -``` - -## AggregateSpecData - -A type whose keys are taken from an `AggregateSpec`, and whose values are the result of the aggregation performed by the corresponding `AggregateField` from the input `AggregateSpec`. - -Signature: - -```typescript -export declare type AggregateSpecData = { - [P in keyof T]: T[P] extends AggregateField ? U : never; -}; -``` - -## ChildUpdateFields - -Helper for calculating the nested fields for a given type T1. This is needed to distribute union types such as `undefined | {...}` (happens for optional props) or `{a: A} | {b: B}`. - -In this use case, `V` is used to distribute the union types of `T[K]` on `Record`, since `T[K]` is evaluated as an expression and not distributed. - -See https://www.typescriptlang.org/docs/handbook/advanced-types.html\#distributive-conditional-types - -Signature: - -```typescript -export declare type ChildUpdateFields = V extends Record ? AddPrefixToKeys> : never; -``` - -## DocumentChangeType - -The type of a `DocumentChange` may be 'added', 'removed', or 'modified'. - -Signature: - -```typescript -export declare type DocumentChangeType = 'added' | 'removed' | 'modified'; -``` - -## FirestoreErrorCode - -The set of Firestore status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.md - -Possible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (e.g. an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation. - -Signature: - -```typescript -export declare type FirestoreErrorCode = 'cancelled' | 'unknown' | 'invalid-argument' | 'deadline-exceeded' | 'not-found' | 'already-exists' | 'permission-denied' | 'resource-exhausted' | 'failed-precondition' | 'aborted' | 'out-of-range' | 'unimplemented' | 'internal' | 'unavailable' | 'data-loss' | 'unauthenticated'; -``` - -## NestedUpdateFields - -For each field (e.g. 'bar'), find all nested keys (e.g. {'bar.baz': T1, 'bar.qux': T2}). Intersect them together to make a single map containing all possible keys that are all marked as optional - -Signature: - -```typescript -export declare type NestedUpdateFields> = UnionToIntersection<{ - [K in keyof T & string]: ChildUpdateFields; -}[keyof T & string]>; -``` - -## OrderByDirection - -The direction of a [orderBy()](./firestore_.md#orderby) clause is specified as 'desc' or 'asc' (descending or ascending). - -Signature: - -```typescript -export declare type OrderByDirection = 'desc' | 'asc'; -``` - -## PartialWithFieldValue - -Similar to Typescript's `Partial`, but allows nested fields to be omitted and FieldValues to be passed in as property values. - -Signature: - -```typescript -export declare type PartialWithFieldValue = Partial | (T extends Primitive ? T : T extends {} ? { - [K in keyof T]?: PartialWithFieldValue | FieldValue; -} : never); -``` - -## Primitive - -Primitive types. - -Signature: - -```typescript -export declare type Primitive = string | number | boolean | undefined | null; -``` - -## QueryConstraintType - -Describes the different query constraints available in this SDK. - -Signature: - -```typescript -export declare type QueryConstraintType = 'where' | 'orderBy' | 'limit' | 'limitToLast' | 'startAt' | 'startAfter' | 'endAt' | 'endBefore'; -``` - -## SetOptions - -An options object that configures the behavior of [setDoc()](./firestore_lite.md#setdoc), and calls. These calls can be configured to perform granular merges instead of overwriting the target documents in their entirety by providing a `SetOptions` with `merge: true`. - -Signature: - -```typescript -export declare type SetOptions = { - readonly merge?: boolean; -} | { - readonly mergeFields?: Array; -}; -``` - -## 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. - -Signature: - -```typescript -export declare type TaskState = 'Error' | 'Running' | 'Success'; -``` - -## UnionToIntersection - -Given a union type `U = T1 | T2 | ...`, returns an intersected type `(T1 & T2 & ...)`. - -Uses distributive conditional types and inference from conditional types. This works because multiple candidates for the same type variable in contra-variant positions causes an intersection type to be inferred. https://www.typescriptlang.org/docs/handbook/advanced-types.html\#type-inference-in-conditional-types https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection-type - -Signature: - -```typescript -export declare type UnionToIntersection = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never; -``` - -## UpdateData - -Update data (for use with [updateDoc()](./firestore_.md#updatedoc)) that consists of field paths (e.g. 'foo' or 'foo.baz') mapped to values. Fields that contain dots reference nested fields within the document. FieldValues can be passed in as property values. - -Signature: - -```typescript -export declare type UpdateData = T extends Primitive ? T : T extends {} ? { - [K in keyof T]?: UpdateData | FieldValue; -} & NestedUpdateFields : Partial; -``` - -## WhereFilterOp - -Filter conditions in a [where()](./firestore_.md#where) clause are specified using the strings '&lt;', '&lt;=', '==', '!=', '&gt;=', '&gt;', 'array-contains', 'in', 'array-contains-any', and 'not-in'. - -Signature: - -```typescript -export declare type WhereFilterOp = '<' | '<=' | '==' | '!=' | '>=' | '>' | 'array-contains' | 'in' | 'array-contains-any' | 'not-in'; -``` - -## WithFieldValue - -Allows FieldValues to be passed in as a property value while maintaining type safety. - -Signature: - -```typescript -export declare type WithFieldValue = T | (T extends Primitive ? T : T extends {} ? { - [K in keyof T]: WithFieldValue | FieldValue; -} : never); -``` diff --git a/docs-devsite/firestore_.persistencesettings.md b/docs-devsite/firestore_.persistencesettings.md deleted file mode 100644 index c84cde1ed13..00000000000 --- a/docs-devsite/firestore_.persistencesettings.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# PersistenceSettings interface -Settings that can be passed to `enableIndexedDbPersistence()` to configure Firestore persistence. - -Signature: - -```typescript -export declare interface PersistenceSettings -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [forceOwnership](./firestore_.persistencesettings.md#persistencesettingsforceownership) | boolean | Whether to force enable persistence for the client. This cannot be used with multi-tab synchronization and is primarily intended for use with Web Workers. Setting this to true will enable persistence, but cause other tabs using persistence to fail. | - -## PersistenceSettings.forceOwnership - -Whether to force enable persistence for the client. This cannot be used with multi-tab synchronization and is primarily intended for use with Web Workers. Setting this to `true` will enable persistence, but cause other tabs using persistence to fail. - -Signature: - -```typescript -forceOwnership?: boolean; -``` diff --git a/docs-devsite/firestore_.query.md b/docs-devsite/firestore_.query.md deleted file mode 100644 index 1961c2cc5f3..00000000000 --- a/docs-devsite/firestore_.query.md +++ /dev/null @@ -1,125 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Query class -A `Query` refers to a query which you can read or listen to. You can also construct refined `Query` objects by adding filters and ordering. - -Signature: - -```typescript -export declare class Query -``` - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)()](./firestore_.query.md#queryconstructor) | | Constructs a new instance of the Query class | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [converter](./firestore_.query.md#queryconverter) | | [FirestoreDataConverter](./firestore_.firestoredataconverter.md#firestoredataconverter_interface)<T> \| null | If provided, the FirestoreDataConverter associated with this instance. | -| [firestore](./firestore_.query.md#queryfirestore) | | [Firestore](./firestore_.firestore.md#firestore_class) | The Firestore instance for the Firestore database (useful for performing transactions, etc.). | -| [type](./firestore_.query.md#querytype) | | 'query' \| 'collection' | The type of this Firestore reference. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [withConverter(converter)](./firestore_.query.md#querywithconverter) | | Removes the current converter. | -| [withConverter(converter)](./firestore_.query.md#querywithconverter) | | Applies a custom data converter to this query, allowing you to use your own custom model objects with Firestore. When you call [getDocs()](./firestore_.md#getdocs) with the returned query, the provided converter will convert between Firestore data and your custom type U. | - -## Query.(constructor) - -Constructs a new instance of the `Query` class - -Signature: - -```typescript -protected constructor(); -``` - -## Query.converter - -If provided, the `FirestoreDataConverter` associated with this instance. - -Signature: - -```typescript -readonly converter: FirestoreDataConverter | null; -``` - -## Query.firestore - -The `Firestore` instance for the Firestore database (useful for performing transactions, etc.). - -Signature: - -```typescript -readonly firestore: Firestore; -``` - -## Query.type - -The type of this Firestore reference. - -Signature: - -```typescript -readonly type: 'query' | 'collection'; -``` - -## Query.withConverter() - -Removes the current converter. - -Signature: - -```typescript -withConverter(converter: null): Query; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| converter | null | null removes the current converter. | - -Returns: - -[Query](./firestore_.query.md#query_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> - -A `Query` that does not use a converter. - -## Query.withConverter() - -Applies a custom data converter to this query, allowing you to use your own custom model objects with Firestore. When you call [getDocs()](./firestore_.md#getdocs) with the returned query, the provided converter will convert between Firestore data and your custom type `U`. - -Signature: - -```typescript -withConverter(converter: FirestoreDataConverter): Query; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| converter | [FirestoreDataConverter](./firestore_.firestoredataconverter.md#firestoredataconverter_interface)<U> | Converts objects to and from Firestore. | - -Returns: - -[Query](./firestore_.query.md#query_class)<U> - -A `Query` that uses the provided converter. - diff --git a/docs-devsite/firestore_.queryconstraint.md b/docs-devsite/firestore_.queryconstraint.md deleted file mode 100644 index eb7a4fca906..00000000000 --- a/docs-devsite/firestore_.queryconstraint.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryConstraint class -A `QueryConstraint` is used to narrow the set of documents returned by a Firestore query. `QueryConstraint`s are created by invoking [where()](./firestore_.md#where), [orderBy()](./firestore_.md#orderby), [startAt()](./firestore_.md#startat), [startAfter()](./firestore_.md#startafter), , [endAt()](./firestore_.md#endat), [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryConstraint`. - -Signature: - -```typescript -export declare abstract class QueryConstraint -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_.queryconstraint.md#queryconstrainttype) | | [QueryConstraintType](./firestore_.md#queryconstrainttype) | The type of this query constraints | - -## QueryConstraint.type - -The type of this query constraints - -Signature: - -```typescript -abstract readonly type: QueryConstraintType; -``` diff --git a/docs-devsite/firestore_.querydocumentsnapshot.md b/docs-devsite/firestore_.querydocumentsnapshot.md deleted file mode 100644 index 0755a11915f..00000000000 --- a/docs-devsite/firestore_.querydocumentsnapshot.md +++ /dev/null @@ -1,54 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryDocumentSnapshot class -A `QueryDocumentSnapshot` contains data read from a document in your Firestore database as part of a query. The document is guaranteed to exist and its data can be extracted with `.data()` or `.get()` to get a specific field. - -A `QueryDocumentSnapshot` offers the same API surface as a `DocumentSnapshot`. Since query results contain only existing documents, the `exists` property will always be true and `data()` will never return 'undefined'. - -Signature: - -```typescript -export declare class QueryDocumentSnapshot extends DocumentSnapshot -``` -Extends: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T> - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [data(options)](./firestore_.querydocumentsnapshot.md#querydocumentsnapshotdata) | | Retrieves all fields in the document as an Object.By default, serverTimestamp() values that have not yet been set to their final value will be returned as null. You can override this by passing an options object. | - -## QueryDocumentSnapshot.data() - -Retrieves all fields in the document as an `Object`. - -By default, `serverTimestamp()` values that have not yet been set to their final value will be returned as `null`. You can override this by passing an options object. - -Signature: - -```typescript -/** @override */ -data(options?: SnapshotOptions): T; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| options | [SnapshotOptions](./firestore_.snapshotoptions.md#snapshotoptions_interface) | An options object to configure how data is retrieved from the snapshot (for example the desired behavior for server timestamps that have not yet been set to their final value). | - -Returns: - -T - -An `Object` containing all fields in the document. - diff --git a/docs-devsite/firestore_.querysnapshot.md b/docs-devsite/firestore_.querysnapshot.md deleted file mode 100644 index 0abb869c003..00000000000 --- a/docs-devsite/firestore_.querysnapshot.md +++ /dev/null @@ -1,128 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QuerySnapshot class -A `QuerySnapshot` contains zero or more `DocumentSnapshot` objects representing the results of a query. The documents can be accessed as an array via the `docs` property or enumerated using the `forEach` method. The number of documents can be determined via the `empty` and `size` properties. - -Signature: - -```typescript -export declare class QuerySnapshot -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [docs](./firestore_.querysnapshot.md#querysnapshotdocs) | | Array<[QueryDocumentSnapshot](./firestore_.querydocumentsnapshot.md#querydocumentsnapshot_class)<T>> | An array of all the documents in the QuerySnapshot. | -| [empty](./firestore_.querysnapshot.md#querysnapshotempty) | | boolean | True if there are no documents in the QuerySnapshot. | -| [metadata](./firestore_.querysnapshot.md#querysnapshotmetadata) | | [SnapshotMetadata](./firestore_.snapshotmetadata.md#snapshotmetadata_class) | Metadata about this snapshot, concerning its source and if it has local modifications. | -| [query](./firestore_.querysnapshot.md#querysnapshotquery) | | [Query](./firestore_.query.md#query_class)<T> | The query on which you called get or onSnapshot in order to get this QuerySnapshot. | -| [size](./firestore_.querysnapshot.md#querysnapshotsize) | | number | The number of documents in the QuerySnapshot. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [docChanges(options)](./firestore_.querysnapshot.md#querysnapshotdocchanges) | | Returns an array of the documents changes since the last snapshot. If this is the first snapshot, all documents will be in the list as 'added' changes. | -| [forEach(callback, thisArg)](./firestore_.querysnapshot.md#querysnapshotforeach) | | Enumerates all of the documents in the QuerySnapshot. | - -## QuerySnapshot.docs - -An array of all the documents in the `QuerySnapshot`. - -Signature: - -```typescript -get docs(): Array>; -``` - -## QuerySnapshot.empty - -True if there are no documents in the `QuerySnapshot`. - -Signature: - -```typescript -get empty(): boolean; -``` - -## QuerySnapshot.metadata - -Metadata about this snapshot, concerning its source and if it has local modifications. - -Signature: - -```typescript -readonly metadata: SnapshotMetadata; -``` - -## QuerySnapshot.query - -The query on which you called `get` or `onSnapshot` in order to get this `QuerySnapshot`. - -Signature: - -```typescript -readonly query: Query; -``` - -## QuerySnapshot.size - -The number of documents in the `QuerySnapshot`. - -Signature: - -```typescript -get size(): number; -``` - -## QuerySnapshot.docChanges() - -Returns an array of the documents changes since the last snapshot. If this is the first snapshot, all documents will be in the list as 'added' changes. - -Signature: - -```typescript -docChanges(options?: SnapshotListenOptions): Array>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| options | [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | SnapshotListenOptions that control whether metadata-only changes (i.e. only DocumentSnapshot.metadata changed) should trigger snapshot events. | - -Returns: - -Array<[DocumentChange](./firestore_.documentchange.md#documentchange_interface)<T>> - -## QuerySnapshot.forEach() - -Enumerates all of the documents in the `QuerySnapshot`. - -Signature: - -```typescript -forEach(callback: (result: QueryDocumentSnapshot) => void, thisArg?: unknown): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| callback | (result: [QueryDocumentSnapshot](./firestore_.querydocumentsnapshot.md#querydocumentsnapshot_class)<T>) => void | A callback to be called with a QueryDocumentSnapshot for each document in the snapshot. | -| thisArg | unknown | The this binding for the callback. | - -Returns: - -void - diff --git a/docs-devsite/firestore_.snapshotlistenoptions.md b/docs-devsite/firestore_.snapshotlistenoptions.md deleted file mode 100644 index dba8308fc02..00000000000 --- a/docs-devsite/firestore_.snapshotlistenoptions.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# SnapshotListenOptions interface -An options object that can be passed to [onSnapshot()](./firestore_.md#onsnapshot) and [QuerySnapshot.docChanges()](./firestore_.querysnapshot.md#querysnapshotdocchanges) to control which types of changes to include in the result set. - -Signature: - -```typescript -export declare interface SnapshotListenOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [includeMetadataChanges](./firestore_.snapshotlistenoptions.md#snapshotlistenoptionsincludemetadatachanges) | boolean | Include a change even if only the metadata of the query or of a document changed. Default is false. | - -## SnapshotListenOptions.includeMetadataChanges - -Include a change even if only the metadata of the query or of a document changed. Default is false. - -Signature: - -```typescript -readonly includeMetadataChanges?: boolean; -``` diff --git a/docs-devsite/firestore_.snapshotmetadata.md b/docs-devsite/firestore_.snapshotmetadata.md deleted file mode 100644 index 6f062ed1c92..00000000000 --- a/docs-devsite/firestore_.snapshotmetadata.md +++ /dev/null @@ -1,75 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# SnapshotMetadata class -Metadata about a snapshot, describing the state of the snapshot. - -Signature: - -```typescript -export declare class SnapshotMetadata -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [fromCache](./firestore_.snapshotmetadata.md#snapshotmetadatafromcache) | | boolean | True if the snapshot was created from cached data rather than guaranteed up-to-date server data. If your listener has opted into metadata updates (via SnapshotListenOptions) you will receive another snapshot with fromCache set to false once the client has received up-to-date data from the backend. | -| [hasPendingWrites](./firestore_.snapshotmetadata.md#snapshotmetadatahaspendingwrites) | | boolean | True if the snapshot contains the result of local writes (for example set() or update() calls) that have not yet been committed to the backend. If your listener has opted into metadata updates (via SnapshotListenOptions) you will receive another snapshot with hasPendingWrites equal to false once the writes have been committed to the backend. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [isEqual(other)](./firestore_.snapshotmetadata.md#snapshotmetadataisequal) | | Returns true if this SnapshotMetadata is equal to the provided one. | - -## SnapshotMetadata.fromCache - -True if the snapshot was created from cached data rather than guaranteed up-to-date server data. If your listener has opted into metadata updates (via `SnapshotListenOptions`) you will receive another snapshot with `fromCache` set to false once the client has received up-to-date data from the backend. - -Signature: - -```typescript -readonly fromCache: boolean; -``` - -## SnapshotMetadata.hasPendingWrites - -True if the snapshot contains the result of local writes (for example `set()` or `update()` calls) that have not yet been committed to the backend. If your listener has opted into metadata updates (via `SnapshotListenOptions`) you will receive another snapshot with `hasPendingWrites` equal to false once the writes have been committed to the backend. - -Signature: - -```typescript -readonly hasPendingWrites: boolean; -``` - -## SnapshotMetadata.isEqual() - -Returns true if this `SnapshotMetadata` is equal to the provided one. - -Signature: - -```typescript -isEqual(other: SnapshotMetadata): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| other | [SnapshotMetadata](./firestore_.snapshotmetadata.md#snapshotmetadata_class) | The SnapshotMetadata to compare against. | - -Returns: - -boolean - -true if this `SnapshotMetadata` is equal to the provided one. - diff --git a/docs-devsite/firestore_.snapshotoptions.md b/docs-devsite/firestore_.snapshotoptions.md deleted file mode 100644 index e7ccd715552..00000000000 --- a/docs-devsite/firestore_.snapshotoptions.md +++ /dev/null @@ -1,41 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# SnapshotOptions interface -Options that configure how data is retrieved from a `DocumentSnapshot` (for example the desired behavior for server timestamps that have not yet been set to their final value). - -Signature: - -```typescript -export declare interface SnapshotOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [serverTimestamps](./firestore_.snapshotoptions.md#snapshotoptionsservertimestamps) | 'estimate' \| 'previous' \| 'none' | If set, controls the return value for server timestamps that have not yet been set to their final value.By specifying 'estimate', pending server timestamps return an estimate based on the local clock. This estimate will differ from the final value and cause these values to change once the server result becomes available.By specifying 'previous', pending timestamps will be ignored and return their previous value instead.If omitted or set to 'none', null will be returned by default until the server value becomes available. | - -## SnapshotOptions.serverTimestamps - -If set, controls the return value for server timestamps that have not yet been set to their final value. - -By specifying 'estimate', pending server timestamps return an estimate based on the local clock. This estimate will differ from the final value and cause these values to change once the server result becomes available. - -By specifying 'previous', pending timestamps will be ignored and return their previous value instead. - -If omitted or set to 'none', `null` will be returned by default until the server value becomes available. - -Signature: - -```typescript -readonly serverTimestamps?: 'estimate' | 'previous' | 'none'; -``` diff --git a/docs-devsite/firestore_.timestamp.md b/docs-devsite/firestore_.timestamp.md deleted file mode 100644 index ef75f07fdd5..00000000000 --- a/docs-devsite/firestore_.timestamp.md +++ /dev/null @@ -1,243 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Timestamp class -A `Timestamp` represents a point in time independent of any time zone or calendar, represented as seconds and fractions of seconds at nanosecond resolution in UTC Epoch time. - -It is encoded using the Proleptic Gregorian Calendar which extends the Gregorian calendar backwards to year one. It is encoded assuming all minutes are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. - -For examples and further specifications, refer to the [Timestamp definition](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto). - -Signature: - -```typescript -export declare class Timestamp -``` - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(seconds, nanoseconds)](./firestore_.timestamp.md#timestampconstructor) | | Creates a new timestamp. | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [nanoseconds](./firestore_.timestamp.md#timestampnanoseconds) | | number | The fractions of a second at nanosecond resolution.\* | -| [seconds](./firestore_.timestamp.md#timestampseconds) | | number | The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [fromDate(date)](./firestore_.timestamp.md#timestampfromdate) | static | Creates a new timestamp from the given date. | -| [fromMillis(milliseconds)](./firestore_.timestamp.md#timestampfrommillis) | static | Creates a new timestamp from the given number of milliseconds. | -| [isEqual(other)](./firestore_.timestamp.md#timestampisequal) | | Returns true if this Timestamp is equal to the provided one. | -| [now()](./firestore_.timestamp.md#timestampnow) | static | Creates a new timestamp with the current date, with millisecond precision. | -| [toDate()](./firestore_.timestamp.md#timestamptodate) | | Converts a Timestamp to a JavaScript Date object. This conversion causes a loss of precision since Date objects only support millisecond precision. | -| [toJSON()](./firestore_.timestamp.md#timestamptojson) | | Returns a JSON-serializable representation of this Timestamp. | -| [toMillis()](./firestore_.timestamp.md#timestamptomillis) | | Converts a Timestamp to a numeric timestamp (in milliseconds since epoch). This operation causes a loss of precision. | -| [toString()](./firestore_.timestamp.md#timestamptostring) | | Returns a textual representation of this Timestamp. | -| [valueOf()](./firestore_.timestamp.md#timestampvalueof) | | Converts this object to a primitive string, which allows Timestamp objects to be compared using the >, <=, >= and > operators. | - -## Timestamp.(constructor) - -Creates a new timestamp. - -Signature: - -```typescript -constructor( - seconds: number, - nanoseconds: number); -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| seconds | number | The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive. | -| nanoseconds | number | The non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanoseconds values that count forward in time. Must be from 0 to 999,999,999 inclusive. | - -## Timestamp.nanoseconds - -The fractions of a second at nanosecond resolution.\* - -Signature: - -```typescript -readonly nanoseconds: number; -``` - -## Timestamp.seconds - -The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. - -Signature: - -```typescript -readonly seconds: number; -``` - -## Timestamp.fromDate() - -Creates a new timestamp from the given date. - -Signature: - -```typescript -static fromDate(date: Date): Timestamp; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| date | Date | The date to initialize the Timestamp from. | - -Returns: - -[Timestamp](./firestore_.timestamp.md#timestamp_class) - -A new `Timestamp` representing the same point in time as the given date. - -## Timestamp.fromMillis() - -Creates a new timestamp from the given number of milliseconds. - -Signature: - -```typescript -static fromMillis(milliseconds: number): Timestamp; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| milliseconds | number | Number of milliseconds since Unix epoch 1970-01-01T00:00:00Z. | - -Returns: - -[Timestamp](./firestore_.timestamp.md#timestamp_class) - -A new `Timestamp` representing the same point in time as the given number of milliseconds. - -## Timestamp.isEqual() - -Returns true if this `Timestamp` is equal to the provided one. - -Signature: - -```typescript -isEqual(other: Timestamp): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| other | [Timestamp](./firestore_.timestamp.md#timestamp_class) | The Timestamp to compare against. | - -Returns: - -boolean - -true if this `Timestamp` is equal to the provided one. - -## Timestamp.now() - -Creates a new timestamp with the current date, with millisecond precision. - -Signature: - -```typescript -static now(): Timestamp; -``` -Returns: - -[Timestamp](./firestore_.timestamp.md#timestamp_class) - -a new timestamp representing the current date. - -## Timestamp.toDate() - -Converts a `Timestamp` to a JavaScript `Date` object. This conversion causes a loss of precision since `Date` objects only support millisecond precision. - -Signature: - -```typescript -toDate(): Date; -``` -Returns: - -Date - -JavaScript `Date` object representing the same point in time as this `Timestamp`, with millisecond precision. - -## Timestamp.toJSON() - -Returns a JSON-serializable representation of this `Timestamp`. - -Signature: - -```typescript -toJSON(): { - seconds: number; - nanoseconds: number; - }; -``` -Returns: - -{ seconds: number; nanoseconds: number; } - -## Timestamp.toMillis() - -Converts a `Timestamp` to a numeric timestamp (in milliseconds since epoch). This operation causes a loss of precision. - -Signature: - -```typescript -toMillis(): number; -``` -Returns: - -number - -The point in time corresponding to this timestamp, represented as the number of milliseconds since Unix epoch 1970-01-01T00:00:00Z. - -## Timestamp.toString() - -Returns a textual representation of this `Timestamp`. - -Signature: - -```typescript -toString(): string; -``` -Returns: - -string - -## Timestamp.valueOf() - -Converts this object to a primitive string, which allows `Timestamp` objects to be compared using the `>`, `<=`, `>=` and `>` operators. - -Signature: - -```typescript -valueOf(): string; -``` -Returns: - -string - diff --git a/docs-devsite/firestore_.transaction.md b/docs-devsite/firestore_.transaction.md deleted file mode 100644 index 24f0690bea4..00000000000 --- a/docs-devsite/firestore_.transaction.md +++ /dev/null @@ -1,190 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Transaction class -A reference to a transaction. - -The `Transaction` object passed to a transaction's `updateFunction` provides the methods to read and write data within the transaction context. See [runTransaction()](./firestore_.md#runtransaction). - -Signature: - -```typescript -export declare class Transaction -``` - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [delete(documentRef)](./firestore_.transaction.md#transactiondelete) | | Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). | -| [get(documentRef)](./firestore_.transaction.md#transactionget) | | Reads the document referenced by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). | -| [set(documentRef, data)](./firestore_.transaction.md#transactionset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. | -| [set(documentRef, data, options)](./firestore_.transaction.md#transactionset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document. | -| [update(documentRef, data)](./firestore_.transaction.md#transactionupdate) | | Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. | -| [update(documentRef, field, value, moreFieldsAndValues)](./firestore_.transaction.md#transactionupdate) | | Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist.Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects. | - -## Transaction.delete() - -Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). - -Signature: - -```typescript -delete(documentRef: DocumentReference): this; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to the document to be deleted. | - -Returns: - -this - -This `Transaction` instance. Used for chaining method calls. - -## Transaction.get() - -Reads the document referenced by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). - -Signature: - -```typescript -get(documentRef: DocumentReference): Promise>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be read. | - -Returns: - -Promise<[DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>> - -A `DocumentSnapshot` with the read data. - -## Transaction.set() - -Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. - -Signature: - -```typescript -set(documentRef: DocumentReference, data: WithFieldValue): this; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | -| data | [WithFieldValue](./firestore_.md#withfieldvalue)<T> | An object of the fields and values for the document. | - -Returns: - -this - -This `Transaction` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not a valid Firestore document. - -## Transaction.set() - -Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. - -Signature: - -```typescript -set(documentRef: DocumentReference, data: PartialWithFieldValue, options: SetOptions): this; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | -| data | [PartialWithFieldValue](./firestore_.md#partialwithfieldvalue)<T> | An object of the fields and values for the document. | -| options | [SetOptions](./firestore_.md#setoptions) | An object to configure the set behavior. | - -Returns: - -this - -This `Transaction` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not a valid Firestore document. - -## Transaction.update() - -Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. - -Signature: - -```typescript -update(documentRef: DocumentReference, data: UpdateData): this; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be updated. | -| data | [UpdateData](./firestore_.md#updatedata)<T> | An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document. | - -Returns: - -this - -This `Transaction` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not valid Firestore data. - -## Transaction.update() - -Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. - -Nested fields can be updated by providing dot-separated field path strings or by providing `FieldPath` objects. - -Signature: - -```typescript -update(documentRef: DocumentReference, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): this; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to the document to be updated. | -| field | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The first field to update. | -| value | unknown | The first value. | -| moreFieldsAndValues | unknown\[\] | Additional key/value pairs. | - -Returns: - -this - -This `Transaction` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not valid Firestore data. - diff --git a/docs-devsite/firestore_.transactionoptions.md b/docs-devsite/firestore_.transactionoptions.md deleted file mode 100644 index 1e7a5aedd28..00000000000 --- a/docs-devsite/firestore_.transactionoptions.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# TransactionOptions interface -Options to customize transaction behavior. - -Signature: - -```typescript -export declare interface TransactionOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [maxAttempts](./firestore_.transactionoptions.md#transactionoptionsmaxattempts) | number | Maximum number of attempts to commit, after which transaction fails. Default is 5. | - -## TransactionOptions.maxAttempts - -Maximum number of attempts to commit, after which transaction fails. Default is 5. - -Signature: - -```typescript -readonly maxAttempts?: number; -``` diff --git a/docs-devsite/firestore_.unsubscribe.md b/docs-devsite/firestore_.unsubscribe.md deleted file mode 100644 index 8bafb4f9ee8..00000000000 --- a/docs-devsite/firestore_.unsubscribe.md +++ /dev/null @@ -1,19 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Unsubscribe interface -A function returned by `onSnapshot()` that removes the listener when invoked. - -Signature: - -```typescript -export declare interface Unsubscribe -``` diff --git a/docs-devsite/firestore_.writebatch.md b/docs-devsite/firestore_.writebatch.md deleted file mode 100644 index 878cb66810a..00000000000 --- a/docs-devsite/firestore_.writebatch.md +++ /dev/null @@ -1,181 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# WriteBatch class -A write batch, used to perform multiple writes as a single atomic unit. - -A `WriteBatch` object can be acquired by calling [writeBatch()](./firestore_.md#writebatch). It provides methods for adding writes to the write batch. None of the writes will be committed (or visible locally) until [WriteBatch.commit()](./firestore_.writebatch.md#writebatchcommit) is called. - -Signature: - -```typescript -export declare class WriteBatch -``` - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [commit()](./firestore_.writebatch.md#writebatchcommit) | | Commits all of the writes in this write batch as a single atomic unit.The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | -| [delete(documentRef)](./firestore_.writebatch.md#writebatchdelete) | | Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). | -| [set(documentRef, data)](./firestore_.writebatch.md#writebatchset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. | -| [set(documentRef, data, options)](./firestore_.writebatch.md#writebatchset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document. | -| [update(documentRef, data)](./firestore_.writebatch.md#writebatchupdate) | | Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. | -| [update(documentRef, field, value, moreFieldsAndValues)](./firestore_.writebatch.md#writebatchupdate) | | Updates fields in the document referred to by this [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist.Nested fields can be update by providing dot-separated field path strings or by providing FieldPath objects. | - -## WriteBatch.commit() - -Commits all of the writes in this write batch as a single atomic unit. - -The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. - -Signature: - -```typescript -commit(): Promise; -``` -Returns: - -Promise<void> - -A `Promise` resolved once all of the writes in the batch have been successfully written to the backend as an atomic unit (note that it won't resolve while you're offline). - -## WriteBatch.delete() - -Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). - -Signature: - -```typescript -delete(documentRef: DocumentReference): WriteBatch; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to the document to be deleted. | - -Returns: - -[WriteBatch](./firestore_.writebatch.md#writebatch_class) - -This `WriteBatch` instance. Used for chaining method calls. - -## WriteBatch.set() - -Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. - -Signature: - -```typescript -set(documentRef: DocumentReference, data: WithFieldValue): WriteBatch; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | -| data | [WithFieldValue](./firestore_.md#withfieldvalue)<T> | An object of the fields and values for the document. | - -Returns: - -[WriteBatch](./firestore_.writebatch.md#writebatch_class) - -This `WriteBatch` instance. Used for chaining method calls. - -## WriteBatch.set() - -Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. - -Signature: - -```typescript -set(documentRef: DocumentReference, data: PartialWithFieldValue, options: SetOptions): WriteBatch; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | -| data | [PartialWithFieldValue](./firestore_.md#partialwithfieldvalue)<T> | An object of the fields and values for the document. | -| options | [SetOptions](./firestore_.md#setoptions) | An object to configure the set behavior. | - -Returns: - -[WriteBatch](./firestore_.writebatch.md#writebatch_class) - -This `WriteBatch` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not a valid Firestore document. - -## WriteBatch.update() - -Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. - -Signature: - -```typescript -update(documentRef: DocumentReference, data: UpdateData): WriteBatch; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be updated. | -| data | [UpdateData](./firestore_.md#updatedata)<T> | An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document. | - -Returns: - -[WriteBatch](./firestore_.writebatch.md#writebatch_class) - -This `WriteBatch` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not valid Firestore data. - -## WriteBatch.update() - -Updates fields in the document referred to by this [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. - -Nested fields can be update by providing dot-separated field path strings or by providing `FieldPath` objects. - -Signature: - -```typescript -update(documentRef: DocumentReference, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): WriteBatch; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to the document to be updated. | -| field | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The first field to update. | -| value | unknown | The first value. | -| moreFieldsAndValues | unknown\[\] | Additional key value pairs. | - -Returns: - -[WriteBatch](./firestore_.writebatch.md#writebatch_class) - -This `WriteBatch` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not valid Firestore data. - diff --git a/docs-devsite/firestore_lite.aggregatefield.md b/docs-devsite/firestore_lite.aggregatefield.md deleted file mode 100644 index 952b60c9d80..00000000000 --- a/docs-devsite/firestore_lite.aggregatefield.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AggregateField class -Represents an aggregation that can be performed by Firestore. - -Signature: - -```typescript -export declare class AggregateField -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_lite.aggregatefield.md#aggregatefieldtype) | | string | A type string to uniquely identify instances of this class. | - -## AggregateField.type - -A type string to uniquely identify instances of this class. - -Signature: - -```typescript -type: string; -``` diff --git a/docs-devsite/firestore_lite.aggregatequerysnapshot.md b/docs-devsite/firestore_lite.aggregatequerysnapshot.md deleted file mode 100644 index 4b5d3120ba3..00000000000 --- a/docs-devsite/firestore_lite.aggregatequerysnapshot.md +++ /dev/null @@ -1,70 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AggregateQuerySnapshot class -The results of executing an aggregation query. - -Signature: - -```typescript -export declare class AggregateQuerySnapshot -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [query](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshotquery) | | [Query](./firestore_lite.query.md#query_class)<unknown> | The underlying query over which the aggregations recorded in this AggregateQuerySnapshot were performed. | -| [type](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshottype) | | (not declared) | A type string to uniquely identify instances of this class. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [data()](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshotdata) | | Returns the results of the aggregations performed over the underlying query.The keys of the returned object will be the same as those of the AggregateSpec object specified to the aggregation method, and the values will be the corresponding aggregation result. | - -## AggregateQuerySnapshot.query - -The underlying query over which the aggregations recorded in this `AggregateQuerySnapshot` were performed. - -Signature: - -```typescript -readonly query: Query; -``` - -## AggregateQuerySnapshot.type - -A type string to uniquely identify instances of this class. - -Signature: - -```typescript -readonly type = "AggregateQuerySnapshot"; -``` - -## AggregateQuerySnapshot.data() - -Returns the results of the aggregations performed over the underlying query. - -The keys of the returned object will be the same as those of the `AggregateSpec` object specified to the aggregation method, and the values will be the corresponding aggregation result. - -Signature: - -```typescript -data(): AggregateSpecData; -``` -Returns: - -[AggregateSpecData](./firestore_lite.md#aggregatespecdata)<T> - -The results of the aggregations performed over the underlying query. - diff --git a/docs-devsite/firestore_lite.aggregatespec.md b/docs-devsite/firestore_lite.aggregatespec.md deleted file mode 100644 index be06b6941f3..00000000000 --- a/docs-devsite/firestore_lite.aggregatespec.md +++ /dev/null @@ -1,19 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AggregateSpec interface -A type whose property values are all `AggregateField` objects. - -Signature: - -```typescript -export declare interface AggregateSpec -``` diff --git a/docs-devsite/firestore_lite.bytes.md b/docs-devsite/firestore_lite.bytes.md deleted file mode 100644 index 8dec3bdd201..00000000000 --- a/docs-devsite/firestore_lite.bytes.md +++ /dev/null @@ -1,138 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Bytes class -An immutable object representing an array of bytes. - -Signature: - -```typescript -export declare class Bytes -``` - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [fromBase64String(base64)](./firestore_lite.bytes.md#bytesfrombase64string) | static | Creates a new Bytes object from the given Base64 string, converting it to bytes. | -| [fromUint8Array(array)](./firestore_lite.bytes.md#bytesfromuint8array) | static | Creates a new Bytes object from the given Uint8Array. | -| [isEqual(other)](./firestore_lite.bytes.md#bytesisequal) | | Returns true if this Bytes object is equal to the provided one. | -| [toBase64()](./firestore_lite.bytes.md#bytestobase64) | | Returns the underlying bytes as a Base64-encoded string. | -| [toString()](./firestore_lite.bytes.md#bytestostring) | | Returns a string representation of the Bytes object. | -| [toUint8Array()](./firestore_lite.bytes.md#bytestouint8array) | | Returns the underlying bytes in a new Uint8Array. | - -## Bytes.fromBase64String() - -Creates a new `Bytes` object from the given Base64 string, converting it to bytes. - -Signature: - -```typescript -static fromBase64String(base64: string): Bytes; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| base64 | string | The Base64 string used to create the Bytes object. | - -Returns: - -[Bytes](./firestore_lite.bytes.md#bytes_class) - -## Bytes.fromUint8Array() - -Creates a new `Bytes` object from the given Uint8Array. - -Signature: - -```typescript -static fromUint8Array(array: Uint8Array): Bytes; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| array | Uint8Array | The Uint8Array used to create the Bytes object. | - -Returns: - -[Bytes](./firestore_lite.bytes.md#bytes_class) - -## Bytes.isEqual() - -Returns true if this `Bytes` object is equal to the provided one. - -Signature: - -```typescript -isEqual(other: Bytes): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| other | [Bytes](./firestore_lite.bytes.md#bytes_class) | The Bytes object to compare against. | - -Returns: - -boolean - -true if this `Bytes` object is equal to the provided one. - -## Bytes.toBase64() - -Returns the underlying bytes as a Base64-encoded string. - -Signature: - -```typescript -toBase64(): string; -``` -Returns: - -string - -The Base64-encoded string created from the `Bytes` object. - -## Bytes.toString() - -Returns a string representation of the `Bytes` object. - -Signature: - -```typescript -toString(): string; -``` -Returns: - -string - -A string representation of the `Bytes` object. - -## Bytes.toUint8Array() - -Returns the underlying bytes in a new `Uint8Array`. - -Signature: - -```typescript -toUint8Array(): Uint8Array; -``` -Returns: - -Uint8Array - -The Uint8Array created from the `Bytes` object. - diff --git a/docs-devsite/firestore_lite.collectionreference.md b/docs-devsite/firestore_lite.collectionreference.md deleted file mode 100644 index d446560a02f..00000000000 --- a/docs-devsite/firestore_lite.collectionreference.md +++ /dev/null @@ -1,121 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# CollectionReference class -A `CollectionReference` object can be used for adding documents, getting document references, and querying for documents (using [query()](./firestore_.md#query)). - -Signature: - -```typescript -export declare class CollectionReference extends Query -``` -Extends: [Query](./firestore_lite.query.md#query_class)<T> - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [id](./firestore_lite.collectionreference.md#collectionreferenceid) | | string | The collection's identifier. | -| [parent](./firestore_lite.collectionreference.md#collectionreferenceparent) | | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> \| null | A reference to the containing DocumentReference if this is a subcollection. If this isn't a subcollection, the reference is null. | -| [path](./firestore_lite.collectionreference.md#collectionreferencepath) | | string | A string representing the path of the referenced collection (relative to the root of the database). | -| [type](./firestore_lite.collectionreference.md#collectionreferencetype) | | (not declared) | The type of this Firestore reference. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [withConverter(converter)](./firestore_lite.collectionreference.md#collectionreferencewithconverter) | | Applies a custom data converter to this CollectionReference, allowing you to use your own custom model objects with Firestore. When you call [addDoc()](./firestore_.md#adddoc) with the returned CollectionReference instance, the provided converter will convert between Firestore data and your custom type U. | -| [withConverter(converter)](./firestore_lite.collectionreference.md#collectionreferencewithconverter) | | Removes the current converter. | - -## CollectionReference.id - -The collection's identifier. - -Signature: - -```typescript -get id(): string; -``` - -## CollectionReference.parent - -A reference to the containing `DocumentReference` if this is a subcollection. If this isn't a subcollection, the reference is null. - -Signature: - -```typescript -get parent(): DocumentReference | null; -``` - -## CollectionReference.path - -A string representing the path of the referenced collection (relative to the root of the database). - -Signature: - -```typescript -get path(): string; -``` - -## CollectionReference.type - -The type of this Firestore reference. - -Signature: - -```typescript -readonly type = "collection"; -``` - -## CollectionReference.withConverter() - -Applies a custom data converter to this `CollectionReference`, allowing you to use your own custom model objects with Firestore. When you call [addDoc()](./firestore_.md#adddoc) with the returned `CollectionReference` instance, the provided converter will convert between Firestore data and your custom type `U`. - -Signature: - -```typescript -withConverter(converter: FirestoreDataConverter): CollectionReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| converter | [FirestoreDataConverter](./firestore_lite.firestoredataconverter.md#firestoredataconverter_interface)<U> | Converts objects to and from Firestore. | - -Returns: - -[CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<U> - -A `CollectionReference` that uses the provided converter. - -## CollectionReference.withConverter() - -Removes the current converter. - -Signature: - -```typescript -withConverter(converter: null): CollectionReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| converter | null | null removes the current converter. | - -Returns: - -[CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> - -A `CollectionReference` that does not use a converter. - diff --git a/docs-devsite/firestore_lite.documentdata.md b/docs-devsite/firestore_lite.documentdata.md deleted file mode 100644 index 09b5eb64b48..00000000000 --- a/docs-devsite/firestore_lite.documentdata.md +++ /dev/null @@ -1,19 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# DocumentData interface -Document data (for use with [setDoc()](./firestore_lite.md#setdoc)) consists of fields mapped to values. - -Signature: - -```typescript -export declare interface DocumentData -``` diff --git a/docs-devsite/firestore_lite.documentreference.md b/docs-devsite/firestore_lite.documentreference.md deleted file mode 100644 index 0e307435949..00000000000 --- a/docs-devsite/firestore_lite.documentreference.md +++ /dev/null @@ -1,142 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# DocumentReference class -A `DocumentReference` refers to a document location in a Firestore database and can be used to write, read, or listen to the location. The document at the referenced location may or may not exist. - -Signature: - -```typescript -export declare class DocumentReference -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [converter](./firestore_lite.documentreference.md#documentreferenceconverter) | | [FirestoreDataConverter](./firestore_lite.firestoredataconverter.md#firestoredataconverter_interface)<T> \| null | If provided, the FirestoreDataConverter associated with this instance. | -| [firestore](./firestore_lite.documentreference.md#documentreferencefirestore) | | [Firestore](./firestore_lite.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance the document is in. This is useful for performing transactions, for example. | -| [id](./firestore_lite.documentreference.md#documentreferenceid) | | string | The document's identifier within its collection. | -| [parent](./firestore_lite.documentreference.md#documentreferenceparent) | | [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | The collection this DocumentReference belongs to. | -| [path](./firestore_lite.documentreference.md#documentreferencepath) | | string | A string representing the path of the referenced document (relative to the root of the database). | -| [type](./firestore_lite.documentreference.md#documentreferencetype) | | (not declared) | The type of this Firestore reference. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [withConverter(converter)](./firestore_lite.documentreference.md#documentreferencewithconverter) | | Applies a custom data converter to this DocumentReference, allowing you to use your own custom model objects with Firestore. When you call [setDoc()](./firestore_lite.md#setdoc), [getDoc()](./firestore_lite.md#getdoc), etc. with the returned DocumentReference instance, the provided converter will convert between Firestore data and your custom type U. | -| [withConverter(converter)](./firestore_lite.documentreference.md#documentreferencewithconverter) | | Removes the current converter. | - -## DocumentReference.converter - -If provided, the `FirestoreDataConverter` associated with this instance. - -Signature: - -```typescript -readonly converter: FirestoreDataConverter | null; -``` - -## DocumentReference.firestore - -The [Firestore](./firestore_.firestore.md#firestore_class) instance the document is in. This is useful for performing transactions, for example. - -Signature: - -```typescript -readonly firestore: Firestore; -``` - -## DocumentReference.id - -The document's identifier within its collection. - -Signature: - -```typescript -get id(): string; -``` - -## DocumentReference.parent - -The collection this `DocumentReference` belongs to. - -Signature: - -```typescript -get parent(): CollectionReference; -``` - -## DocumentReference.path - -A string representing the path of the referenced document (relative to the root of the database). - -Signature: - -```typescript -get path(): string; -``` - -## DocumentReference.type - -The type of this Firestore reference. - -Signature: - -```typescript -readonly type = "document"; -``` - -## DocumentReference.withConverter() - -Applies a custom data converter to this `DocumentReference`, allowing you to use your own custom model objects with Firestore. When you call [setDoc()](./firestore_lite.md#setdoc), [getDoc()](./firestore_lite.md#getdoc), etc. with the returned `DocumentReference` instance, the provided converter will convert between Firestore data and your custom type `U`. - -Signature: - -```typescript -withConverter(converter: FirestoreDataConverter): DocumentReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| converter | [FirestoreDataConverter](./firestore_lite.firestoredataconverter.md#firestoredataconverter_interface)<U> | Converts objects to and from Firestore. | - -Returns: - -[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<U> - -A `DocumentReference` that uses the provided converter. - -## DocumentReference.withConverter() - -Removes the current converter. - -Signature: - -```typescript -withConverter(converter: null): DocumentReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| converter | null | null removes the current converter. | - -Returns: - -[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> - -A `DocumentReference` that does not use a converter. - diff --git a/docs-devsite/firestore_lite.documentsnapshot.md b/docs-devsite/firestore_lite.documentsnapshot.md deleted file mode 100644 index cfea1feb919..00000000000 --- a/docs-devsite/firestore_lite.documentsnapshot.md +++ /dev/null @@ -1,125 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# DocumentSnapshot class -A `DocumentSnapshot` contains data read from a document in your Firestore database. The data can be extracted with `.data()` or `.get()` to get a specific field. - -For a `DocumentSnapshot` that points to a non-existing document, any data access will return 'undefined'. You can use the `exists()` method to explicitly verify a document's existence. - -Signature: - -```typescript -export declare class DocumentSnapshot -``` - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)()](./firestore_lite.documentsnapshot.md#documentsnapshotconstructor) | | Constructs a new instance of the DocumentSnapshot class | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [id](./firestore_lite.documentsnapshot.md#documentsnapshotid) | | string | Property of the DocumentSnapshot that provides the document's ID. | -| [ref](./firestore_lite.documentsnapshot.md#documentsnapshotref) | | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | The DocumentReference for the document included in the DocumentSnapshot. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [data()](./firestore_lite.documentsnapshot.md#documentsnapshotdata) | | Retrieves all fields in the document as an Object. Returns undefined if the document doesn't exist. | -| [exists()](./firestore_lite.documentsnapshot.md#documentsnapshotexists) | | Signals whether or not the document at the snapshot's location exists. | -| [get(fieldPath)](./firestore_lite.documentsnapshot.md#documentsnapshotget) | | Retrieves the field specified by fieldPath. Returns undefined if the document or field doesn't exist. | - -## DocumentSnapshot.(constructor) - -Constructs a new instance of the `DocumentSnapshot` class - -Signature: - -```typescript -protected constructor(); -``` - -## DocumentSnapshot.id - -Property of the `DocumentSnapshot` that provides the document's ID. - -Signature: - -```typescript -get id(): string; -``` - -## DocumentSnapshot.ref - -The `DocumentReference` for the document included in the `DocumentSnapshot`. - -Signature: - -```typescript -get ref(): DocumentReference; -``` - -## DocumentSnapshot.data() - -Retrieves all fields in the document as an `Object`. Returns `undefined` if the document doesn't exist. - -Signature: - -```typescript -data(): T | undefined; -``` -Returns: - -T \| undefined - -An `Object` containing all fields in the document or `undefined` if the document doesn't exist. - -## DocumentSnapshot.exists() - -Signals whether or not the document at the snapshot's location exists. - -Signature: - -```typescript -exists(): this is QueryDocumentSnapshot; -``` -Returns: - -this is [QueryDocumentSnapshot](./firestore_lite.querydocumentsnapshot.md#querydocumentsnapshot_class)<T> - -true if the document exists. - -## DocumentSnapshot.get() - -Retrieves the field specified by `fieldPath`. Returns `undefined` if the document or field doesn't exist. - -Signature: - -```typescript -get(fieldPath: string | FieldPath): any; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldPath | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The path (for example 'foo' or 'foo.bar') to a specific field. | - -Returns: - -any - -The data at the specified field location or undefined if no such field exists in the document. - diff --git a/docs-devsite/firestore_lite.fieldpath.md b/docs-devsite/firestore_lite.fieldpath.md deleted file mode 100644 index ea449fc065b..00000000000 --- a/docs-devsite/firestore_lite.fieldpath.md +++ /dev/null @@ -1,72 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FieldPath class -A `FieldPath` refers to a field in a document. The path may consist of a single field name (referring to a top-level field in the document), or a list of field names (referring to a nested field in the document). - -Create a `FieldPath` by providing field names. If more than one field name is provided, the path will point to a nested field in a document. - -Signature: - -```typescript -export declare class FieldPath -``` - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(fieldNames)](./firestore_lite.fieldpath.md#fieldpathconstructor) | | Creates a FieldPath from the provided field names. If more than one field name is provided, the path will point to a nested field in a document. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [isEqual(other)](./firestore_lite.fieldpath.md#fieldpathisequal) | | Returns true if this FieldPath is equal to the provided one. | - -## FieldPath.(constructor) - -Creates a `FieldPath` from the provided field names. If more than one field name is provided, the path will point to a nested field in a document. - -Signature: - -```typescript -constructor(...fieldNames: string[]); -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldNames | string\[\] | A list of field names. | - -## FieldPath.isEqual() - -Returns true if this `FieldPath` is equal to the provided one. - -Signature: - -```typescript -isEqual(other: FieldPath): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| other | [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The FieldPath to compare against. | - -Returns: - -boolean - -true if this `FieldPath` is equal to the provided one. - diff --git a/docs-devsite/firestore_lite.fieldvalue.md b/docs-devsite/firestore_lite.fieldvalue.md deleted file mode 100644 index 454693c9771..00000000000 --- a/docs-devsite/firestore_lite.fieldvalue.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FieldValue class -Sentinel values that can be used when writing document fields with `set()` or `update()`. - -Signature: - -```typescript -export declare abstract class FieldValue -``` - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [isEqual(other)](./firestore_lite.fieldvalue.md#fieldvalueisequal) | | Compares FieldValues for equality. | - -## FieldValue.isEqual() - -Compares `FieldValue`s for equality. - -Signature: - -```typescript -abstract isEqual(other: FieldValue): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| other | [FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) | | - -Returns: - -boolean - diff --git a/docs-devsite/firestore_lite.firestore.md b/docs-devsite/firestore_lite.firestore.md deleted file mode 100644 index 2edac7aa130..00000000000 --- a/docs-devsite/firestore_lite.firestore.md +++ /dev/null @@ -1,68 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Firestore class -The Cloud Firestore service interface. - -Do not call this constructor directly. Instead, use [getFirestore()](./firestore_.md#getfirestore). - -Signature: - -```typescript -export declare class Firestore -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [app](./firestore_lite.firestore.md#firestoreapp) | | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this Firestore service instance. | -| [type](./firestore_lite.firestore.md#firestoretype) | | 'firestore-lite' \| 'firestore' | Whether it's a Firestore or Firestore Lite instance. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [toJSON()](./firestore_lite.firestore.md#firestoretojson) | | Returns a JSON-serializable representation of this Firestore instance. | - -## Firestore.app - -The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this `Firestore` service instance. - -Signature: - -```typescript -get app(): FirebaseApp; -``` - -## Firestore.type - -Whether it's a Firestore or Firestore Lite instance. - -Signature: - -```typescript -type: 'firestore-lite' | 'firestore'; -``` - -## Firestore.toJSON() - -Returns a JSON-serializable representation of this `Firestore` instance. - -Signature: - -```typescript -toJSON(): object; -``` -Returns: - -object - diff --git a/docs-devsite/firestore_lite.firestoredataconverter.md b/docs-devsite/firestore_lite.firestoredataconverter.md deleted file mode 100644 index 00510e0c22b..00000000000 --- a/docs-devsite/firestore_lite.firestoredataconverter.md +++ /dev/null @@ -1,130 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FirestoreDataConverter interface -Converter used by `withConverter()` to transform user objects of type `T` into Firestore data. - -Using the converter allows you to specify generic type arguments when storing and retrieving objects from Firestore. - -Signature: - -```typescript -export declare interface FirestoreDataConverter -``` - -## Methods - -| Method | Description | -| --- | --- | -| [fromFirestore(snapshot)](./firestore_lite.firestoredataconverter.md#firestoredataconverterfromfirestore) | Called by the Firestore SDK to convert Firestore data into an object of type T. You can access your data by calling: snapshot.data(). | -| [toFirestore(modelObject)](./firestore_lite.firestoredataconverter.md#firestoredataconvertertofirestore) | Called by the Firestore SDK to convert a custom model object of type T into a plain Javascript object (suitable for writing directly to the Firestore database). Used with [setDoc()](./firestore_lite.md#setdoc), and .The WithFieldValue<T> type extends T to also allow FieldValues such as [deleteField()](./firestore_.md#deletefield) to be used as property values. | -| [toFirestore(modelObject, options)](./firestore_lite.firestoredataconverter.md#firestoredataconvertertofirestore) | Called by the Firestore SDK to convert a custom model object of type T into a plain Javascript object (suitable for writing directly to the Firestore database). Used with [setDoc()](./firestore_lite.md#setdoc), and with merge:true or mergeFields.The PartialWithFieldValue<T> type extends Partial<T> to allow FieldValues such as [arrayUnion()](./firestore_.md#arrayunion) to be used as property values. It also supports nested Partial by allowing nested fields to be omitted. | - -## FirestoreDataConverter.fromFirestore() - -Called by the Firestore SDK to convert Firestore data into an object of type T. You can access your data by calling: `snapshot.data()`. - -Signature: - -```typescript -fromFirestore(snapshot: QueryDocumentSnapshot): T; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| snapshot | [QueryDocumentSnapshot](./firestore_lite.querydocumentsnapshot.md#querydocumentsnapshot_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> | A QueryDocumentSnapshot containing your data and metadata. | - -Returns: - -T - -## FirestoreDataConverter.toFirestore() - -Called by the Firestore SDK to convert a custom model object of type `T` into a plain Javascript object (suitable for writing directly to the Firestore database). Used with [setDoc()](./firestore_lite.md#setdoc), and . - -The `WithFieldValue` type extends `T` to also allow FieldValues such as [deleteField()](./firestore_.md#deletefield) to be used as property values. - -Signature: - -```typescript -toFirestore(modelObject: WithFieldValue): DocumentData; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| modelObject | [WithFieldValue](./firestore_lite.md#withfieldvalue)<T> | | - -Returns: - -[DocumentData](./firestore_lite.documentdata.md#documentdata_interface) - -## FirestoreDataConverter.toFirestore() - -Called by the Firestore SDK to convert a custom model object of type `T` into a plain Javascript object (suitable for writing directly to the Firestore database). Used with [setDoc()](./firestore_lite.md#setdoc), and with `merge:true` or `mergeFields`. - -The `PartialWithFieldValue` type extends `Partial` to allow FieldValues such as [arrayUnion()](./firestore_.md#arrayunion) to be used as property values. It also supports nested `Partial` by allowing nested fields to be omitted. - -Signature: - -```typescript -toFirestore(modelObject: PartialWithFieldValue, options: SetOptions): DocumentData; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| modelObject | [PartialWithFieldValue](./firestore_lite.md#partialwithfieldvalue)<T> | | -| options | [SetOptions](./firestore_lite.md#setoptions) | | - -Returns: - -[DocumentData](./firestore_lite.documentdata.md#documentdata_interface) - -### Example - - -```typescript -class Post { - constructor(readonly title: string, readonly author: string) {} - - toString(): string { - return this.title + ', by ' + this.author; - } -} - -const postConverter = { - toFirestore(post: WithFieldValue): DocumentData { - return {title: post.title, author: post.author}; - }, - fromFirestore(snapshot: QueryDocumentSnapshot): Post { - const data = snapshot.data(options)!; - return new Post(data.title, data.author); - } -}; - -const postSnap = await firebase.firestore() - .collection('posts') - .withConverter(postConverter) - .doc().get(); -const post = postSnap.data(); -if (post !== undefined) { - post.title; // string - post.toString(); // Should be defined - post.someNonExistentProperty; // TS error -} - -``` - diff --git a/docs-devsite/firestore_lite.firestoreerror.md b/docs-devsite/firestore_lite.firestoreerror.md deleted file mode 100644 index e3c6dd23029..00000000000 --- a/docs-devsite/firestore_lite.firestoreerror.md +++ /dev/null @@ -1,58 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FirestoreError class -An error returned by a Firestore operation. - -Signature: - -```typescript -export declare class FirestoreError extends FirebaseError -``` -Extends: [FirebaseError](./util.firebaseerror.md#firebaseerror_class) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [code](./firestore_lite.firestoreerror.md#firestoreerrorcode) | | [FirestoreErrorCode](./firestore_lite.md#firestoreerrorcode) | The backend error code associated with this error. | -| [message](./firestore_lite.firestoreerror.md#firestoreerrormessage) | | string | A custom error description. | -| [stack](./firestore_lite.firestoreerror.md#firestoreerrorstack) | | string | The stack of the error. | - -## FirestoreError.code - -The backend error code associated with this error. - -Signature: - -```typescript -readonly code: FirestoreErrorCode; -``` - -## FirestoreError.message - -A custom error description. - -Signature: - -```typescript -readonly message: string; -``` - -## FirestoreError.stack - -The stack of the error. - -Signature: - -```typescript -readonly stack?: string; -``` diff --git a/docs-devsite/firestore_lite.geopoint.md b/docs-devsite/firestore_lite.geopoint.md deleted file mode 100644 index 23576c41d8d..00000000000 --- a/docs-devsite/firestore_lite.geopoint.md +++ /dev/null @@ -1,117 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# GeoPoint class -An immutable object representing a geographic location in Firestore. The location is represented as latitude/longitude pair. - -Latitude values are in the range of \[-90, 90\]. Longitude values are in the range of \[-180, 180\]. - -Signature: - -```typescript -export declare class GeoPoint -``` - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(latitude, longitude)](./firestore_lite.geopoint.md#geopointconstructor) | | Creates a new immutable GeoPoint object with the provided latitude and longitude values. | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [latitude](./firestore_lite.geopoint.md#geopointlatitude) | | number | The latitude of this GeoPoint instance. | -| [longitude](./firestore_lite.geopoint.md#geopointlongitude) | | number | The longitude of this GeoPoint instance. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [isEqual(other)](./firestore_lite.geopoint.md#geopointisequal) | | Returns true if this GeoPoint is equal to the provided one. | -| [toJSON()](./firestore_lite.geopoint.md#geopointtojson) | | Returns a JSON-serializable representation of this GeoPoint. | - -## GeoPoint.(constructor) - -Creates a new immutable `GeoPoint` object with the provided latitude and longitude values. - -Signature: - -```typescript -constructor(latitude: number, longitude: number); -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| latitude | number | The latitude as number between -90 and 90. | -| longitude | number | The longitude as number between -180 and 180. | - -## GeoPoint.latitude - -The latitude of this `GeoPoint` instance. - -Signature: - -```typescript -get latitude(): number; -``` - -## GeoPoint.longitude - -The longitude of this `GeoPoint` instance. - -Signature: - -```typescript -get longitude(): number; -``` - -## GeoPoint.isEqual() - -Returns true if this `GeoPoint` is equal to the provided one. - -Signature: - -```typescript -isEqual(other: GeoPoint): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| other | [GeoPoint](./firestore_lite.geopoint.md#geopoint_class) | The GeoPoint to compare against. | - -Returns: - -boolean - -true if this `GeoPoint` is equal to the provided one. - -## GeoPoint.toJSON() - -Returns a JSON-serializable representation of this GeoPoint. - -Signature: - -```typescript -toJSON(): { - latitude: number; - longitude: number; - }; -``` -Returns: - -{ latitude: number; longitude: number; } - diff --git a/docs-devsite/firestore_lite.md b/docs-devsite/firestore_lite.md deleted file mode 100644 index e3f3653e61b..00000000000 --- a/docs-devsite/firestore_lite.md +++ /dev/null @@ -1,1412 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# @firebase/firestore/lite - -## Functions - -| Function | Description | -| --- | --- | -| [addDoc(reference, data)](./firestore_lite.md#adddoc) | Add a new document to specified CollectionReference with the given data, assigning it a document ID automatically.The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | -| [aggregateQuerySnapshotEqual(left, right)](./firestore_lite.md#aggregatequerysnapshotequal) | Compares two AggregateQuerySnapshot instances for equality.Two AggregateQuerySnapshot instances are considered "equal" if they have underlying queries that compare equal, and the same data. | -| [arrayRemove(elements)](./firestore_lite.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_lite.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. | -| [collection(firestore, path, pathSegments)](./firestore_lite.md#collection) | Gets a CollectionReference instance that refers to the collection at the specified absolute path. | -| [collection(reference, path, pathSegments)](./firestore_lite.md#collection) | Gets a CollectionReference instance that refers to a subcollection of reference at the the specified relative path. | -| [collection(reference, path, pathSegments)](./firestore_lite.md#collection) | Gets a CollectionReference instance that refers to a subcollection of reference at the the specified relative path. | -| [collectionGroup(firestore, collectionId)](./firestore_lite.md#collectiongroup) | Creates and returns a new Query instance that includes all documents in the database that are contained in a collection or subcollection with the given collectionId. | -| [connectFirestoreEmulator(firestore, host, port, options)](./firestore_lite.md#connectfirestoreemulator) | Modify this instance to communicate with the Cloud Firestore emulator.Note: This must be called before this instance has been used to do any operations. | -| [deleteDoc(reference)](./firestore_lite.md#deletedoc) | Deletes the document referred to by the specified DocumentReference.The deletion will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the delete fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | -| [deleteField()](./firestore_lite.md#deletefield) | Returns a sentinel for use with [updateDoc()](./firestore_lite.md#updatedoc) or [setDoc()](./firestore_lite.md#setdoc) with {merge: true} to mark a field for deletion. | -| [doc(firestore, path, pathSegments)](./firestore_lite.md#doc) | Gets a DocumentReference instance that refers to the document at the specified absolute path. | -| [doc(reference, path, pathSegments)](./firestore_lite.md#doc) | Gets a DocumentReference instance that refers to a document within reference at the specified relative path. If no path is specified, an automatically-generated unique ID will be used for the returned DocumentReference. | -| [doc(reference, path, pathSegments)](./firestore_lite.md#doc) | Gets a DocumentReference instance that refers to a document within reference at the specified relative path. | -| [documentId()](./firestore_lite.md#documentid) | Returns a special sentinel FieldPath to refer to the ID of a document. It can be used in queries to sort or filter by the document ID. | -| [endAt(snapshot)](./firestore_lite.md#endat) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end at the provided document (inclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | -| [endAt(fieldValues)](./firestore_lite.md#endat) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | -| [endBefore(snapshot)](./firestore_lite.md#endbefore) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | -| [endBefore(fieldValues)](./firestore_lite.md#endbefore) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | -| [getCount(query)](./firestore_lite.md#getcount) | Calculates the number of documents in the result set of the given query, without actually downloading the documents.Using this function to count the documents is efficient because only the final count, not the documents' data, is downloaded. This function can even count the documents if the result set would be prohibitively large to download entirely (e.g. thousands of documents). | -| [getDoc(reference)](./firestore_lite.md#getdoc) | Reads the document referred to by the specified document reference.All documents are directly fetched from the server, even if the document was previously read or modified. Recent modifications are only reflected in the retrieved DocumentSnapshot if they have already been applied by the backend. If the client is offline, the read fails. If you like to use caching or see local modifications, please use the full Firestore SDK. | -| [getDocs(query)](./firestore_lite.md#getdocs) | Executes the query and returns the results as a [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class).All queries are executed directly by the server, even if the the query was previously executed. Recent modifications are only reflected in the retrieved results if they have already been applied by the backend. If the client is offline, the operation fails. To see previously cached result and local modifications, use the full Firestore SDK. | -| [getFirestore()](./firestore_lite.md#getfirestore) | Returns the existing default [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(app)](./firestore_lite.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. | -| [increment(n)](./firestore_lite.md#increment) | 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 increment the field's current value by the given value.If either the operand or the current field value uses floating point precision, all arithmetic follows IEEE 754 semantics. If both values are integers, values outside of JavaScript's safe number range (Number.MIN_SAFE_INTEGER to Number.MAX_SAFE_INTEGER) are also subject to precision loss. Furthermore, once processed by the Firestore backend, all integer operations are capped between -2^63 and 2^63-1.If the current field value is not of type number, or if the field does not yet exist, the transformation sets the field to the given value. | -| [initializeFirestore(app, settings)](./firestore_lite.md#initializefirestore) | Initializes a new instance of Cloud Firestore with the provided settings. Can only be called before any other functions, including [getFirestore()](./firestore_.md#getfirestore). If the custom settings are empty, this function is equivalent to calling [getFirestore()](./firestore_.md#getfirestore). | -| [limit(limit)](./firestore_lite.md#limit) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that only returns the first matching documents. | -| [limitToLast(limit)](./firestore_lite.md#limittolast) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that only returns the last matching documents.You must specify at least one orderBy clause for limitToLast queries, otherwise an exception will be thrown during execution. | -| [orderBy(fieldPath, directionStr)](./firestore_lite.md#orderby) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that sorts the query result by the specified field, optionally in descending order instead of ascending. | -| [query(query, queryConstraints)](./firestore_lite.md#query) | Creates a new immutable instance of [Query](./firestore_.query.md#query_class) that is extended to also include additional query constraints. | -| [queryEqual(left, right)](./firestore_lite.md#queryequal) | Returns true if the provided queries point to the same collection and apply the same constraints. | -| [refEqual(left, right)](./firestore_lite.md#refequal) | Returns true if the provided references are equal. | -| [runTransaction(firestore, updateFunction, options)](./firestore_lite.md#runtransaction) | Executes the given updateFunction and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, Cloud Firestore retries the updateFunction. If it fails to commit after 5 attempts, the transaction fails.The maximum number of writes allowed in a single transaction is 500. | -| [serverTimestamp()](./firestore_lite.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. | -| [setDoc(reference, data)](./firestore_lite.md#setdoc) | Writes to the document referred to by the specified DocumentReference. If the document does not yet exist, it will be created.The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | -| [setDoc(reference, data, options)](./firestore_lite.md#setdoc) | Writes to the document referred to by the specified DocumentReference. If the document does not yet exist, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document.The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | -| [setLogLevel(logLevel)](./firestore_lite.md#setloglevel) | Sets the verbosity of Cloud Firestore logs (debug, error, or silent). | -| [snapshotEqual(left, right)](./firestore_lite.md#snapshotequal) | Returns true if the provided snapshots are equal. | -| [startAfter(snapshot)](./firestore_lite.md#startafter) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | -| [startAfter(fieldValues)](./firestore_lite.md#startafter) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | -| [startAt(snapshot)](./firestore_lite.md#startat) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of this query. | -| [startAt(fieldValues)](./firestore_lite.md#startat) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | -| [terminate(firestore)](./firestore_lite.md#terminate) | Terminates the provided Firestore instance.After calling terminate() only the clearIndexedDbPersistence() functions may be used. Any other function will throw a FirestoreError. Termination does not cancel any pending writes, and any promises that are awaiting a response from the server will not be resolved.To restart after termination, create a new instance of Firestore with [getFirestore()](./firestore_.md#getfirestore).Note: Under normal circumstances, calling terminate() is not required. This function is useful only when you want to force this instance to release all of its resources or in combination with [clearIndexedDbPersistence()](./firestore_.md#clearindexeddbpersistence) to ensure that all local state is destroyed between test runs. | -| [updateDoc(reference, data)](./firestore_lite.md#updatedoc) | Updates fields in the document referred to by the specified DocumentReference. The update will fail if applied to a document that does not exist.The result of this update will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the update fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | -| [updateDoc(reference, field, value, moreFieldsAndValues)](./firestore_lite.md#updatedoc) | Updates fields in the document referred to by the specified DocumentReference The update will fail if applied to a document that does not exist.Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects.The result of this update will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the update fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | -| [where(fieldPath, opStr, value)](./firestore_lite.md#where) | Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that enforces that documents must contain the specified field and that the value should satisfy the relation constraint provided. | -| [writeBatch(firestore)](./firestore_lite.md#writebatch) | Creates a write batch, used for performing multiple writes as a single atomic operation. The maximum number of writes allowed in a single WriteBatch is 500.The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | - -## Classes - -| Class | Description | -| --- | --- | -| [AggregateField](./firestore_lite.aggregatefield.md#aggregatefield_class) | Represents an aggregation that can be performed by Firestore. | -| [AggregateQuerySnapshot](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshot_class) | The results of executing an aggregation query. | -| [Bytes](./firestore_lite.bytes.md#bytes_class) | An immutable object representing an array of bytes. | -| [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class) | A CollectionReference object can be used for adding documents, getting document references, and querying for documents (using [query()](./firestore_.md#query)). | -| [DocumentReference](./firestore_lite.documentreference.md#documentreference_class) | A DocumentReference refers to a document location in a Firestore database and can be used to write, read, or listen to the location. The document at the referenced location may or may not exist. | -| [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class) | A DocumentSnapshot contains data read from a document in your Firestore database. The data can be extracted with .data() or .get(<field>) to get a specific field.For a DocumentSnapshot that points to a non-existing document, any data access will return 'undefined'. You can use the exists() method to explicitly verify a document's existence. | -| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | A FieldPath refers to a field in a document. The path may consist of a single field name (referring to a top-level field in the document), or a list of field names (referring to a nested field in the document).Create a FieldPath by providing field names. If more than one field name is provided, the path will point to a nested field in a document. | -| [FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) | Sentinel values that can be used when writing document fields with set() or update(). | -| [Firestore](./firestore_lite.firestore.md#firestore_class) | The Cloud Firestore service interface.Do not call this constructor directly. Instead, use [getFirestore()](./firestore_.md#getfirestore). | -| [FirestoreError](./firestore_lite.firestoreerror.md#firestoreerror_class) | An error returned by a Firestore operation. | -| [GeoPoint](./firestore_lite.geopoint.md#geopoint_class) | An immutable object representing a geographic location in Firestore. The location is represented as latitude/longitude pair.Latitude values are in the range of \[-90, 90\]. Longitude values are in the range of \[-180, 180\]. | -| [Query](./firestore_lite.query.md#query_class) | A Query refers to a query which you can read or listen to. You can also construct refined Query objects by adding filters and ordering. | -| [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) | A QueryConstraint is used to narrow the set of documents returned by a Firestore query. QueryConstraints are created by invoking [where()](./firestore_.md#where), [orderBy()](./firestore_.md#orderby), [startAt()](./firestore_.md#startat), [startAfter()](./firestore_.md#startafter), , [endAt()](./firestore_.md#endat), [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryConstraint. | -| [QueryDocumentSnapshot](./firestore_lite.querydocumentsnapshot.md#querydocumentsnapshot_class) | A QueryDocumentSnapshot contains data read from a document in your Firestore database as part of a query. The document is guaranteed to exist and its data can be extracted with .data() or .get(<field>) to get a specific field.A QueryDocumentSnapshot offers the same API surface as a DocumentSnapshot. Since query results contain only existing documents, the exists property will always be true and data() will never return 'undefined'. | -| [QuerySnapshot](./firestore_lite.querysnapshot.md#querysnapshot_class) | A QuerySnapshot contains zero or more DocumentSnapshot objects representing the results of a query. The documents can be accessed as an array via the docs property or enumerated using the forEach method. The number of documents can be determined via the empty and size properties. | -| [Timestamp](./firestore_lite.timestamp.md#timestamp_class) | A Timestamp represents a point in time independent of any time zone or calendar, represented as seconds and fractions of seconds at nanosecond resolution in UTC Epoch time.It is encoded using the Proleptic Gregorian Calendar which extends the Gregorian calendar backwards to year one. It is encoded assuming all minutes are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.For examples and further specifications, refer to the [Timestamp definition](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto). | -| [Transaction](./firestore_lite.transaction.md#transaction_class) | A reference to a transaction.The Transaction object passed to a transaction's updateFunction provides the methods to read and write data within the transaction context. See [runTransaction()](./firestore_.md#runtransaction). | -| [WriteBatch](./firestore_lite.writebatch.md#writebatch_class) | A write batch, used to perform multiple writes as a single atomic unit.A WriteBatch object can be acquired by calling [writeBatch()](./firestore_.md#writebatch). It provides methods for adding writes to the write batch. None of the writes will be committed (or visible locally) until [WriteBatch.commit()](./firestore_.writebatch.md#writebatchcommit) is called. | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [AggregateSpec](./firestore_lite.aggregatespec.md#aggregatespec_interface) | A type whose property values are all AggregateField objects. | -| [DocumentData](./firestore_lite.documentdata.md#documentdata_interface) | Document data (for use with [setDoc()](./firestore_lite.md#setdoc)) consists of fields mapped to values. | -| [FirestoreDataConverter](./firestore_lite.firestoredataconverter.md#firestoredataconverter_interface) | Converter used by withConverter() to transform user objects of type T into Firestore data.Using the converter allows you to specify generic type arguments when storing and retrieving objects from Firestore. | -| [Settings](./firestore_lite.settings.md#settings_interface) | Specifies custom configurations for your Cloud Firestore instance. You must set these before invoking any other methods. | -| [TransactionOptions](./firestore_lite.transactionoptions.md#transactionoptions_interface) | Options to customize transaction behavior. | - -## Type Aliases - -| Type Alias | Description | -| --- | --- | -| [AddPrefixToKeys](./firestore_lite.md#addprefixtokeys) | Returns a new map where every key is prefixed with the outer key appended to a dot. | -| [AggregateFieldType](./firestore_lite.md#aggregatefieldtype) | The union of all AggregateField types that are supported by Firestore. | -| [AggregateSpecData](./firestore_lite.md#aggregatespecdata) | A type whose keys are taken from an AggregateSpec, and whose values are the result of the aggregation performed by the corresponding AggregateField from the input AggregateSpec. | -| [ChildUpdateFields](./firestore_lite.md#childupdatefields) | Helper for calculating the nested fields for a given type T1. This is needed to distribute union types such as undefined | {...} (happens for optional props) or {a: A} | {b: B}.In this use case, V is used to distribute the union types of T[K] on Record, since T[K] is evaluated as an expression and not distributed.See https://www.typescriptlang.org/docs/handbook/advanced-types.html\#distributive-conditional-types | -| [FirestoreErrorCode](./firestore_lite.md#firestoreerrorcode) | The set of Firestore status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.mdPossible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (e.g. an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation. | -| [NestedUpdateFields](./firestore_lite.md#nestedupdatefields) | For each field (e.g. 'bar'), find all nested keys (e.g. {'bar.baz': T1, 'bar.qux': T2}). Intersect them together to make a single map containing all possible keys that are all marked as optional | -| [OrderByDirection](./firestore_lite.md#orderbydirection) | The direction of a [orderBy()](./firestore_.md#orderby) clause is specified as 'desc' or 'asc' (descending or ascending). | -| [PartialWithFieldValue](./firestore_lite.md#partialwithfieldvalue) | Similar to Typescript's Partial<T>, but allows nested fields to be omitted and FieldValues to be passed in as property values. | -| [Primitive](./firestore_lite.md#primitive) | Primitive types. | -| [QueryConstraintType](./firestore_lite.md#queryconstrainttype) | Describes the different query constraints available in this SDK. | -| [SetOptions](./firestore_lite.md#setoptions) | An options object that configures the behavior of [setDoc()](./firestore_lite.md#setdoc), and calls. These calls can be configured to perform granular merges instead of overwriting the target documents in their entirety by providing a SetOptions with merge: true. | -| [UnionToIntersection](./firestore_lite.md#uniontointersection) | Given a union type U = T1 | T2 | ..., returns an intersected type (T1 & T2 & ...).Uses distributive conditional types and inference from conditional types. This works because multiple candidates for the same type variable in contra-variant positions causes an intersection type to be inferred. https://www.typescriptlang.org/docs/handbook/advanced-types.html\#type-inference-in-conditional-types https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection-type | -| [UpdateData](./firestore_lite.md#updatedata) | Update data (for use with [updateDoc()](./firestore_.md#updatedoc)) that consists of field paths (e.g. 'foo' or 'foo.baz') mapped to values. Fields that contain dots reference nested fields within the document. FieldValues can be passed in as property values. | -| [WhereFilterOp](./firestore_lite.md#wherefilterop) | Filter conditions in a [where()](./firestore_.md#where) clause are specified using the strings '&lt;', '&lt;=', '==', '!=', '&gt;=', '&gt;', 'array-contains', 'in', 'array-contains-any', and 'not-in'. | -| [WithFieldValue](./firestore_lite.md#withfieldvalue) | Allows FieldValues to be passed in as a property value while maintaining type safety. | - -## addDoc() - -Add a new document to specified `CollectionReference` with the given data, assigning it a document ID automatically. - -The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. - -Signature: - -```typescript -export declare function addDoc(reference: CollectionReference, data: WithFieldValue): Promise>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | A reference to the collection to add this document to. | -| data | [WithFieldValue](./firestore_lite.md#withfieldvalue)<T> | An Object containing the data for the new document. | - -Returns: - -Promise<[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T>> - -A `Promise` resolved with a `DocumentReference` pointing to the newly created document after it has been written to the backend. - -## Exceptions - -Error - If the provided input is not a valid Firestore document. - -## aggregateQuerySnapshotEqual() - -Compares two `AggregateQuerySnapshot` instances for equality. - -Two `AggregateQuerySnapshot` instances are considered "equal" if they have underlying queries that compare equal, and the same data. - -Signature: - -```typescript -export declare function aggregateQuerySnapshotEqual(left: AggregateQuerySnapshot, right: AggregateQuerySnapshot): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| left | [AggregateQuerySnapshot](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<T> | The first AggregateQuerySnapshot to compare. | -| right | [AggregateQuerySnapshot](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<T> | The second AggregateQuerySnapshot to compare. | - -Returns: - -boolean - -`true` if the objects are "equal", as defined above, or `false` otherwise. - -## 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. - -Signature: - -```typescript -export declare function arrayRemove(...elements: unknown[]): FieldValue; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| elements | unknown\[\] | The elements to remove from the array. | - -Returns: - -[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) - -The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()` - -## 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. - -Signature: - -```typescript -export declare function arrayUnion(...elements: unknown[]): FieldValue; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| elements | unknown\[\] | The elements to union into the array. | - -Returns: - -[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) - -The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()`. - -## collection() - -Gets a `CollectionReference` instance that refers to the collection at the specified absolute path. - -Signature: - -```typescript -export declare function collection(firestore: Firestore, path: string, ...pathSegments: string[]): CollectionReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | A reference to the root Firestore instance. | -| path | string | A slash-separated path to a collection. | -| pathSegments | string\[\] | Additional path segments to apply relative to the first argument. | - -Returns: - -[CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> - -The `CollectionReference` instance. - -## Exceptions - -If the final path has an even number of segments and does not point to a collection. - -## collection() - -Gets a `CollectionReference` instance that refers to a subcollection of `reference` at the the specified relative path. - -Signature: - -```typescript -export declare function collection(reference: CollectionReference, path: string, ...pathSegments: string[]): CollectionReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<unknown> | A reference to a collection. | -| path | string | A slash-separated path to a collection. | -| pathSegments | string\[\] | Additional path segments to apply relative to the first argument. | - -Returns: - -[CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> - -The `CollectionReference` instance. - -## Exceptions - -If the final path has an even number of segments and does not point to a collection. - -## collection() - -Gets a `CollectionReference` instance that refers to a subcollection of `reference` at the the specified relative path. - -Signature: - -```typescript -export declare function collection(reference: DocumentReference, path: string, ...pathSegments: string[]): CollectionReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class) | A reference to a Firestore document. | -| path | string | A slash-separated path to a collection. | -| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | - -Returns: - -[CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> - -The `CollectionReference` instance. - -## Exceptions - -If the final path has an even number of segments and does not point to a collection. - -## collectionGroup() - -Creates and returns a new `Query` instance that includes all documents in the database that are contained in a collection or subcollection with the given `collectionId`. - -Signature: - -```typescript -export declare function collectionGroup(firestore: Firestore, collectionId: string): Query; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | A reference to the root Firestore instance. | -| collectionId | string | Identifies the collections to query over. Every collection or subcollection with this ID as the last segment of its path will be included. Cannot contain a slash. | - -Returns: - -[Query](./firestore_lite.query.md#query_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> - -The created `Query`. - -## connectFirestoreEmulator() - -Modify this instance to communicate with the Cloud Firestore emulator. - -Note: This must be called before this instance has been used to do any operations. - -Signature: - -```typescript -export declare function connectFirestoreEmulator(firestore: Firestore, host: string, port: number, options?: { - mockUserToken?: EmulatorMockTokenOptions | string; -}): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | The Firestore instance to configure to connect to the emulator. | -| host | string | the emulator host (ex: localhost). | -| port | number | the emulator port (ex: 9000). | -| options | { mockUserToken?: [EmulatorMockTokenOptions](./util.md#emulatormocktokenoptions) \| string; } | | - -Returns: - -void - -## deleteDoc() - -Deletes the document referred to by the specified `DocumentReference`. - -The deletion will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the delete fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. - -Signature: - -```typescript -export declare function deleteDoc(reference: DocumentReference): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to the document to delete. | - -Returns: - -Promise<void> - -A `Promise` resolved once the document has been successfully deleted from the backend. - -## deleteField() - -Returns a sentinel for use with [updateDoc()](./firestore_lite.md#updatedoc) or [setDoc()](./firestore_lite.md#setdoc) with `{merge: true}` to mark a field for deletion. - -Signature: - -```typescript -export declare function deleteField(): FieldValue; -``` -Returns: - -[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) - -## doc() - -Gets a `DocumentReference` instance that refers to the document at the specified absolute path. - -Signature: - -```typescript -export declare function doc(firestore: Firestore, path: string, ...pathSegments: string[]): DocumentReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | A reference to the root Firestore instance. | -| path | string | A slash-separated path to a document. | -| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | - -Returns: - -[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> - -The `DocumentReference` instance. - -## Exceptions - -If the final path has an odd number of segments and does not point to a document. - -## doc() - -Gets a `DocumentReference` instance that refers to a document within `reference` at the specified relative path. If no path is specified, an automatically-generated unique ID will be used for the returned `DocumentReference`. - -Signature: - -```typescript -export declare function doc(reference: CollectionReference, path?: string, ...pathSegments: string[]): DocumentReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | A reference to a collection. | -| path | string | A slash-separated path to a document. Has to be omitted to use auto-genrated IDs. | -| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | - -Returns: - -[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> - -The `DocumentReference` instance. - -## Exceptions - -If the final path has an odd number of segments and does not point to a document. - -## doc() - -Gets a `DocumentReference` instance that refers to a document within `reference` at the specified relative path. - -Signature: - -```typescript -export declare function doc(reference: DocumentReference, path: string, ...pathSegments: string[]): DocumentReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to a Firestore document. | -| path | string | A slash-separated path to a document. | -| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | - -Returns: - -[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> - -The `DocumentReference` instance. - -## Exceptions - -If the final path has an odd number of segments and does not point to a document. - -## documentId() - -Returns a special sentinel `FieldPath` to refer to the ID of a document. It can be used in queries to sort or filter by the document ID. - -Signature: - -```typescript -export declare function documentId(): FieldPath; -``` -Returns: - -[FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) - -## endAt() - -Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end at the provided document (inclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. - -Signature: - -```typescript -export declare function endAt(snapshot: DocumentSnapshot): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| snapshot | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to end at. | - -Returns: - -[QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) - -A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()` - -## endAt() - -Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. - -Signature: - -```typescript -export declare function endAt(...fieldValues: unknown[]): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldValues | unknown\[\] | The field values to end this query at, in order of the query's order by. | - -Returns: - -[QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) - -A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()` - -## endBefore() - -Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. - -Signature: - -```typescript -export declare function endBefore(snapshot: DocumentSnapshot): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| snapshot | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to end before. | - -Returns: - -[QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) - -A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()` - -## endBefore() - -Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to end before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. - -Signature: - -```typescript -export declare function endBefore(...fieldValues: unknown[]): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldValues | unknown\[\] | The field values to end this query before, in order of the query's order by. | - -Returns: - -[QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) - -A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()` - -## getCount() - -Calculates the number of documents in the result set of the given query, without actually downloading the documents. - -Using this function to count the documents is efficient because only the final count, not the documents' data, is downloaded. This function can even count the documents if the result set would be prohibitively large to download entirely (e.g. thousands of documents). - -Signature: - -```typescript -export declare function getCount(query: Query): Promise; -}>>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./firestore_lite.query.md#query_class)<unknown> | The query whose result set size to calculate. | - -Returns: - -Promise<[AggregateQuerySnapshot](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<{ count: [AggregateField](./firestore_lite.aggregatefield.md#aggregatefield_class)<number>; }>> - -A Promise that will be resolved with the count; the count can be retrieved from `snapshot.data().count`, where `snapshot` is the `AggregateQuerySnapshot` to which the returned Promise resolves. - -## getDoc() - -Reads the document referred to by the specified document reference. - -All documents are directly fetched from the server, even if the document was previously read or modified. Recent modifications are only reflected in the retrieved `DocumentSnapshot` if they have already been applied by the backend. If the client is offline, the read fails. If you like to use caching or see local modifications, please use the full Firestore SDK. - -Signature: - -```typescript -export declare function getDoc(reference: DocumentReference): Promise>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | The reference of the document to fetch. | - -Returns: - -Promise<[DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<T>> - -A Promise resolved with a `DocumentSnapshot` containing the current document contents. - -## getDocs() - -Executes the query and returns the results as a [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class). - -All queries are executed directly by the server, even if the the query was previously executed. Recent modifications are only reflected in the retrieved results if they have already been applied by the backend. If the client is offline, the operation fails. To see previously cached result and local modifications, use the full Firestore SDK. - -Signature: - -```typescript -export declare function getDocs(query: Query): Promise>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./firestore_lite.query.md#query_class)<T> | The Query to execute. | - -Returns: - -Promise<[QuerySnapshot](./firestore_lite.querysnapshot.md#querysnapshot_class)<T>> - -A Promise that will be resolved with the results of the query. - -## getFirestore() - -Returns the existing default [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: - -```typescript -export declare function getFirestore(): Firestore; -``` -Returns: - -[Firestore](./firestore_lite.firestore.md#firestore_class) - -The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. - -## 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. - -Signature: - -```typescript -export declare function getFirestore(app: FirebaseApp): Firestore; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance that the returned [Firestore](./firestore_.firestore.md#firestore_class) instance is associated with. | - -Returns: - -[Firestore](./firestore_lite.firestore.md#firestore_class) - -The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. - -## increment() - -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 increment the field's current value by the given value. - -If either the operand or the current field value uses floating point precision, all arithmetic follows IEEE 754 semantics. If both values are integers, values outside of JavaScript's safe number range (`Number.MIN_SAFE_INTEGER` to `Number.MAX_SAFE_INTEGER`) are also subject to precision loss. Furthermore, once processed by the Firestore backend, all integer operations are capped between -2^63 and 2^63-1. - -If the current field value is not of type `number`, or if the field does not yet exist, the transformation sets the field to the given value. - -Signature: - -```typescript -export declare function increment(n: number): FieldValue; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| n | number | The value to increment by. | - -Returns: - -[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) - -The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()` - -## initializeFirestore() - -Initializes a new instance of Cloud Firestore with the provided settings. Can only be called before any other functions, including [getFirestore()](./firestore_.md#getfirestore). If the custom settings are empty, this function is equivalent to calling [getFirestore()](./firestore_.md#getfirestore). - -Signature: - -```typescript -export declare function initializeFirestore(app: FirebaseApp, settings: Settings): Firestore; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) with which the Firestore instance will be associated. | -| settings | [Settings](./firestore_lite.settings.md#settings_interface) | A settings object to configure the Firestore instance. | - -Returns: - -[Firestore](./firestore_lite.firestore.md#firestore_class) - -A newly initialized `Firestore` instance. - -## limit() - -Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that only returns the first matching documents. - -Signature: - -```typescript -export declare function limit(limit: number): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| limit | number | The maximum number of items to return. | - -Returns: - -[QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) - -The created [Query](./firestore_.query.md#query_class). - -## limitToLast() - -Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that only returns the last matching documents. - -You must specify at least one `orderBy` clause for `limitToLast` queries, otherwise an exception will be thrown during execution. - -Signature: - -```typescript -export declare function limitToLast(limit: number): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| limit | number | The maximum number of items to return. | - -Returns: - -[QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) - -The created [Query](./firestore_.query.md#query_class). - -## orderBy() - -Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that sorts the query result by the specified field, optionally in descending order instead of ascending. - -Signature: - -```typescript -export declare function orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDirection): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldPath | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The field to sort by. | -| directionStr | [OrderByDirection](./firestore_lite.md#orderbydirection) | Optional direction to sort by ('asc' or 'desc'). If not specified, order will be ascending. | - -Returns: - -[QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) - -The created [Query](./firestore_.query.md#query_class). - -## query() - -Creates a new immutable instance of [Query](./firestore_.query.md#query_class) that is extended to also include additional query constraints. - -Signature: - -```typescript -export declare function query(query: Query, ...queryConstraints: QueryConstraint[]): Query; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./firestore_lite.query.md#query_class)<T> | The [Query](./firestore_.query.md#query_class) instance to use as a base for the new constraints. | -| queryConstraints | [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class)\[\] | The list of [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class)s to apply. | - -Returns: - -[Query](./firestore_lite.query.md#query_class)<T> - -## Exceptions - -if any of the provided query constraints cannot be combined with the existing or new constraints. - -## queryEqual() - -Returns true if the provided queries point to the same collection and apply the same constraints. - -Signature: - -```typescript -export declare function queryEqual(left: Query, right: Query): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| left | [Query](./firestore_lite.query.md#query_class)<T> | A Query to compare. | -| right | [Query](./firestore_lite.query.md#query_class)<T> | A Query to compare. | - -Returns: - -boolean - -true if the references point to the same location in the same Firestore database. - -## refEqual() - -Returns true if the provided references are equal. - -Signature: - -```typescript -export declare function refEqual(left: DocumentReference | CollectionReference, right: DocumentReference | CollectionReference): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| left | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> \| [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | A reference to compare. | -| right | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> \| [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | A reference to compare. | - -Returns: - -boolean - -true if the references point to the same location in the same Firestore database. - -## runTransaction() - -Executes the given `updateFunction` and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, Cloud Firestore retries the `updateFunction`. If it fails to commit after 5 attempts, the transaction fails. - -The maximum number of writes allowed in a single transaction is 500. - -Signature: - -```typescript -export declare function runTransaction(firestore: Firestore, updateFunction: (transaction: Transaction) => Promise, options?: TransactionOptions): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | A reference to the Firestore database to run this transaction against. | -| updateFunction | (transaction: [Transaction](./firestore_lite.transaction.md#transaction_class)) => Promise<T> | The function to execute within the transaction context. | -| options | [TransactionOptions](./firestore_lite.transactionoptions.md#transactionoptions_interface) | An options object to configure maximum number of attempts to commit. | - -Returns: - -Promise<T> - -If the transaction completed successfully or was explicitly aborted (the `updateFunction` returned a failed promise), the promise returned by the `updateFunction `is returned here. Otherwise, if the transaction failed, a rejected promise with the corresponding failure error is returned. - -## 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. - -Signature: - -```typescript -export declare function serverTimestamp(): FieldValue; -``` -Returns: - -[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) - -## setDoc() - -Writes to the document referred to by the specified `DocumentReference`. If the document does not yet exist, it will be created. - -The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. - -Signature: - -```typescript -export declare function setDoc(reference: DocumentReference, data: WithFieldValue): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to write. | -| data | [WithFieldValue](./firestore_lite.md#withfieldvalue)<T> | A map of the fields and values for the document. | - -Returns: - -Promise<void> - -A `Promise` resolved once the data has been successfully written to the backend. - -## Exceptions - -Error - If the provided input is not a valid Firestore document. - -## setDoc() - -Writes to the document referred to by the specified `DocumentReference`. If the document does not yet exist, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. - -The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. - -Signature: - -```typescript -export declare function setDoc(reference: DocumentReference, data: PartialWithFieldValue, options: SetOptions): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to write. | -| data | [PartialWithFieldValue](./firestore_lite.md#partialwithfieldvalue)<T> | A map of the fields and values for the document. | -| options | [SetOptions](./firestore_lite.md#setoptions) | An object to configure the set behavior. | - -Returns: - -Promise<void> - -A `Promise` resolved once the data has been successfully written to the backend. - -## Exceptions - -Error - If the provided input is not a valid Firestore document. - -## setLogLevel() - -Sets the verbosity of Cloud Firestore logs (debug, error, or silent). - -Signature: - -```typescript -export declare function setLogLevel(logLevel: LogLevel): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| logLevel | LogLevel | The verbosity you set for activity and error logging. Can be any of the following values:
  • debug for the most verbose logging level, primarily for debugging.
  • error to log errors only.
  • silent to turn off logging.
| - -Returns: - -void - -## snapshotEqual() - -Returns true if the provided snapshots are equal. - -Signature: - -```typescript -export declare function snapshotEqual(left: DocumentSnapshot | QuerySnapshot, right: DocumentSnapshot | QuerySnapshot): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| left | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<T> \| [QuerySnapshot](./firestore_lite.querysnapshot.md#querysnapshot_class)<T> | A snapshot to compare. | -| right | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<T> \| [QuerySnapshot](./firestore_lite.querysnapshot.md#querysnapshot_class)<T> | A snapshot to compare. | - -Returns: - -boolean - -true if the snapshots are equal. - -## startAfter() - -Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. - -Signature: - -```typescript -export declare function startAfter(snapshot: DocumentSnapshot): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| snapshot | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to start after. | - -Returns: - -[QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) - -A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()` - -## startAfter() - -Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. - -Signature: - -```typescript -export declare function startAfter(...fieldValues: unknown[]): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldValues | unknown\[\] | The field values to start this query after, in order of the query's order by. | - -Returns: - -[QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) - -A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()` - -## startAt() - -Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the `orderBy` of this query. - -Signature: - -```typescript -export declare function startAt(snapshot: DocumentSnapshot): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| snapshot | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to start at. | - -Returns: - -[QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) - -A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()`. - -## startAt() - -Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. - -Signature: - -```typescript -export declare function startAt(...fieldValues: unknown[]): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldValues | unknown\[\] | The field values to start this query at, in order of the query's order by. | - -Returns: - -[QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) - -A [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) to pass to `query()`. - -## terminate() - -Terminates the provided `Firestore` instance. - -After calling `terminate()` only the `clearIndexedDbPersistence()` functions may be used. Any other function will throw a `FirestoreError`. Termination does not cancel any pending writes, and any promises that are awaiting a response from the server will not be resolved. - -To restart after termination, create a new instance of `Firestore` with [getFirestore()](./firestore_.md#getfirestore). - -Note: Under normal circumstances, calling `terminate()` is not required. This function is useful only when you want to force this instance to release all of its resources or in combination with [clearIndexedDbPersistence()](./firestore_.md#clearindexeddbpersistence) to ensure that all local state is destroyed between test runs. - -Signature: - -```typescript -export declare function terminate(firestore: Firestore): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | The Firestore instance to terminate. | - -Returns: - -Promise<void> - -A `Promise` that is resolved when the instance has been successfully terminated. - -## updateDoc() - -Updates fields in the document referred to by the specified `DocumentReference`. The update will fail if applied to a document that does not exist. - -The result of this update will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the update fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. - -Signature: - -```typescript -export declare function updateDoc(reference: DocumentReference, data: UpdateData): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to update. | -| data | [UpdateData](./firestore_lite.md#updatedata)<T> | An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document. | - -Returns: - -Promise<void> - -A `Promise` resolved once the data has been successfully written to the backend. - -## Exceptions - -Error - If the provided input is not valid Firestore data. - -## updateDoc() - -Updates fields in the document referred to by the specified `DocumentReference` The update will fail if applied to a document that does not exist. - -Nested fields can be updated by providing dot-separated field path strings or by providing `FieldPath` objects. - -The result of this update will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the update fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. - -Signature: - -```typescript -export declare function updateDoc(reference: DocumentReference, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to the document to update. | -| field | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The first field to update. | -| value | unknown | The first value. | -| moreFieldsAndValues | unknown\[\] | Additional key value pairs. | - -Returns: - -Promise<void> - -A `Promise` resolved once the data has been successfully written to the backend. - -## Exceptions - -Error - If the provided input is not valid Firestore data. - -## where() - -Creates a [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) that enforces that documents must contain the specified field and that the value should satisfy the relation constraint provided. - -Signature: - -```typescript -export declare function where(fieldPath: string | FieldPath, opStr: WhereFilterOp, value: unknown): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldPath | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The path to compare | -| opStr | [WhereFilterOp](./firestore_lite.md#wherefilterop) | The operation string (e.g "&lt;", "&lt;=", "==", "&lt;", "&lt;=", "!="). | -| value | unknown | The value for comparison | - -Returns: - -[QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) - -The created [Query](./firestore_.query.md#query_class). - -## writeBatch() - -Creates a write batch, used for performing multiple writes as a single atomic operation. The maximum number of writes allowed in a single WriteBatch is 500. - -The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. - -Signature: - -```typescript -export declare function writeBatch(firestore: Firestore): WriteBatch; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | | - -Returns: - -[WriteBatch](./firestore_lite.writebatch.md#writebatch_class) - -A `WriteBatch` that can be used to atomically execute multiple writes. - -## AddPrefixToKeys - -Returns a new map where every key is prefixed with the outer key appended to a dot. - -Signature: - -```typescript -export declare type AddPrefixToKeys> = { - [K in keyof T & string as `${Prefix}.${K}`]+?: T[K]; -}; -``` - -## AggregateFieldType - -The union of all `AggregateField` types that are supported by Firestore. - -Signature: - -```typescript -export declare type AggregateFieldType = AggregateField; -``` - -## AggregateSpecData - -A type whose keys are taken from an `AggregateSpec`, and whose values are the result of the aggregation performed by the corresponding `AggregateField` from the input `AggregateSpec`. - -Signature: - -```typescript -export declare type AggregateSpecData = { - [P in keyof T]: T[P] extends AggregateField ? U : never; -}; -``` - -## ChildUpdateFields - -Helper for calculating the nested fields for a given type T1. This is needed to distribute union types such as `undefined | {...}` (happens for optional props) or `{a: A} | {b: B}`. - -In this use case, `V` is used to distribute the union types of `T[K]` on `Record`, since `T[K]` is evaluated as an expression and not distributed. - -See https://www.typescriptlang.org/docs/handbook/advanced-types.html\#distributive-conditional-types - -Signature: - -```typescript -export declare type ChildUpdateFields = V extends Record ? AddPrefixToKeys> : never; -``` - -## FirestoreErrorCode - -The set of Firestore status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.md - -Possible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (e.g. an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation. - -Signature: - -```typescript -export declare type FirestoreErrorCode = 'cancelled' | 'unknown' | 'invalid-argument' | 'deadline-exceeded' | 'not-found' | 'already-exists' | 'permission-denied' | 'resource-exhausted' | 'failed-precondition' | 'aborted' | 'out-of-range' | 'unimplemented' | 'internal' | 'unavailable' | 'data-loss' | 'unauthenticated'; -``` - -## NestedUpdateFields - -For each field (e.g. 'bar'), find all nested keys (e.g. {'bar.baz': T1, 'bar.qux': T2}). Intersect them together to make a single map containing all possible keys that are all marked as optional - -Signature: - -```typescript -export declare type NestedUpdateFields> = UnionToIntersection<{ - [K in keyof T & string]: ChildUpdateFields; -}[keyof T & string]>; -``` - -## OrderByDirection - -The direction of a [orderBy()](./firestore_.md#orderby) clause is specified as 'desc' or 'asc' (descending or ascending). - -Signature: - -```typescript -export declare type OrderByDirection = 'desc' | 'asc'; -``` - -## PartialWithFieldValue - -Similar to Typescript's `Partial`, but allows nested fields to be omitted and FieldValues to be passed in as property values. - -Signature: - -```typescript -export declare type PartialWithFieldValue = Partial | (T extends Primitive ? T : T extends {} ? { - [K in keyof T]?: PartialWithFieldValue | FieldValue; -} : never); -``` - -## Primitive - -Primitive types. - -Signature: - -```typescript -export declare type Primitive = string | number | boolean | undefined | null; -``` - -## QueryConstraintType - -Describes the different query constraints available in this SDK. - -Signature: - -```typescript -export declare type QueryConstraintType = 'where' | 'orderBy' | 'limit' | 'limitToLast' | 'startAt' | 'startAfter' | 'endAt' | 'endBefore'; -``` - -## SetOptions - -An options object that configures the behavior of [setDoc()](./firestore_lite.md#setdoc), and calls. These calls can be configured to perform granular merges instead of overwriting the target documents in their entirety by providing a `SetOptions` with `merge: true`. - -Signature: - -```typescript -export declare type SetOptions = { - readonly merge?: boolean; -} | { - readonly mergeFields?: Array; -}; -``` - -## UnionToIntersection - -Given a union type `U = T1 | T2 | ...`, returns an intersected type `(T1 & T2 & ...)`. - -Uses distributive conditional types and inference from conditional types. This works because multiple candidates for the same type variable in contra-variant positions causes an intersection type to be inferred. https://www.typescriptlang.org/docs/handbook/advanced-types.html\#type-inference-in-conditional-types https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection-type - -Signature: - -```typescript -export declare type UnionToIntersection = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never; -``` - -## UpdateData - -Update data (for use with [updateDoc()](./firestore_.md#updatedoc)) that consists of field paths (e.g. 'foo' or 'foo.baz') mapped to values. Fields that contain dots reference nested fields within the document. FieldValues can be passed in as property values. - -Signature: - -```typescript -export declare type UpdateData = T extends Primitive ? T : T extends {} ? { - [K in keyof T]?: UpdateData | FieldValue; -} & NestedUpdateFields : Partial; -``` - -## WhereFilterOp - -Filter conditions in a [where()](./firestore_.md#where) clause are specified using the strings '&lt;', '&lt;=', '==', '!=', '&gt;=', '&gt;', 'array-contains', 'in', 'array-contains-any', and 'not-in'. - -Signature: - -```typescript -export declare type WhereFilterOp = '<' | '<=' | '==' | '!=' | '>=' | '>' | 'array-contains' | 'in' | 'array-contains-any' | 'not-in'; -``` - -## WithFieldValue - -Allows FieldValues to be passed in as a property value while maintaining type safety. - -Signature: - -```typescript -export declare type WithFieldValue = T | (T extends Primitive ? T : T extends {} ? { - [K in keyof T]: WithFieldValue | FieldValue; -} : never); -``` diff --git a/docs-devsite/firestore_lite.query.md b/docs-devsite/firestore_lite.query.md deleted file mode 100644 index f2eac7560dc..00000000000 --- a/docs-devsite/firestore_lite.query.md +++ /dev/null @@ -1,125 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Query class -A `Query` refers to a query which you can read or listen to. You can also construct refined `Query` objects by adding filters and ordering. - -Signature: - -```typescript -export declare class Query -``` - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)()](./firestore_lite.query.md#queryconstructor) | | Constructs a new instance of the Query class | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [converter](./firestore_lite.query.md#queryconverter) | | [FirestoreDataConverter](./firestore_lite.firestoredataconverter.md#firestoredataconverter_interface)<T> \| null | If provided, the FirestoreDataConverter associated with this instance. | -| [firestore](./firestore_lite.query.md#queryfirestore) | | [Firestore](./firestore_lite.firestore.md#firestore_class) | The Firestore instance for the Firestore database (useful for performing transactions, etc.). | -| [type](./firestore_lite.query.md#querytype) | | 'query' \| 'collection' | The type of this Firestore reference. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [withConverter(converter)](./firestore_lite.query.md#querywithconverter) | | Removes the current converter. | -| [withConverter(converter)](./firestore_lite.query.md#querywithconverter) | | Applies a custom data converter to this query, allowing you to use your own custom model objects with Firestore. When you call [getDocs()](./firestore_.md#getdocs) with the returned query, the provided converter will convert between Firestore data and your custom type U. | - -## Query.(constructor) - -Constructs a new instance of the `Query` class - -Signature: - -```typescript -protected constructor(); -``` - -## Query.converter - -If provided, the `FirestoreDataConverter` associated with this instance. - -Signature: - -```typescript -readonly converter: FirestoreDataConverter | null; -``` - -## Query.firestore - -The `Firestore` instance for the Firestore database (useful for performing transactions, etc.). - -Signature: - -```typescript -readonly firestore: Firestore; -``` - -## Query.type - -The type of this Firestore reference. - -Signature: - -```typescript -readonly type: 'query' | 'collection'; -``` - -## Query.withConverter() - -Removes the current converter. - -Signature: - -```typescript -withConverter(converter: null): Query; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| converter | null | null removes the current converter. | - -Returns: - -[Query](./firestore_lite.query.md#query_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> - -A `Query` that does not use a converter. - -## Query.withConverter() - -Applies a custom data converter to this query, allowing you to use your own custom model objects with Firestore. When you call [getDocs()](./firestore_.md#getdocs) with the returned query, the provided converter will convert between Firestore data and your custom type `U`. - -Signature: - -```typescript -withConverter(converter: FirestoreDataConverter): Query; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| converter | [FirestoreDataConverter](./firestore_lite.firestoredataconverter.md#firestoredataconverter_interface)<U> | Converts objects to and from Firestore. | - -Returns: - -[Query](./firestore_lite.query.md#query_class)<U> - -A `Query` that uses the provided converter. - diff --git a/docs-devsite/firestore_lite.queryconstraint.md b/docs-devsite/firestore_lite.queryconstraint.md deleted file mode 100644 index 13bda202cb5..00000000000 --- a/docs-devsite/firestore_lite.queryconstraint.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryConstraint class -A `QueryConstraint` is used to narrow the set of documents returned by a Firestore query. `QueryConstraint`s are created by invoking [where()](./firestore_.md#where), [orderBy()](./firestore_.md#orderby), [startAt()](./firestore_.md#startat), [startAfter()](./firestore_.md#startafter), , [endAt()](./firestore_.md#endat), [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryConstraint`. - -Signature: - -```typescript -export declare abstract class QueryConstraint -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_lite.queryconstraint.md#queryconstrainttype) | | [QueryConstraintType](./firestore_lite.md#queryconstrainttype) | The type of this query constraints | - -## QueryConstraint.type - -The type of this query constraints - -Signature: - -```typescript -abstract readonly type: QueryConstraintType; -``` diff --git a/docs-devsite/firestore_lite.querydocumentsnapshot.md b/docs-devsite/firestore_lite.querydocumentsnapshot.md deleted file mode 100644 index 356d7ecaeed..00000000000 --- a/docs-devsite/firestore_lite.querydocumentsnapshot.md +++ /dev/null @@ -1,45 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryDocumentSnapshot class -A `QueryDocumentSnapshot` contains data read from a document in your Firestore database as part of a query. The document is guaranteed to exist and its data can be extracted with `.data()` or `.get()` to get a specific field. - -A `QueryDocumentSnapshot` offers the same API surface as a `DocumentSnapshot`. Since query results contain only existing documents, the `exists` property will always be true and `data()` will never return 'undefined'. - -Signature: - -```typescript -export declare class QueryDocumentSnapshot extends DocumentSnapshot -``` -Extends: [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<T> - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [data()](./firestore_lite.querydocumentsnapshot.md#querydocumentsnapshotdata) | | Retrieves all fields in the document as an Object. | - -## QueryDocumentSnapshot.data() - -Retrieves all fields in the document as an `Object`. - -Signature: - -```typescript -/** @override */ -data(): T; -``` -Returns: - -T - -An `Object` containing all fields in the document. - diff --git a/docs-devsite/firestore_lite.querysnapshot.md b/docs-devsite/firestore_lite.querysnapshot.md deleted file mode 100644 index 8e805af948d..00000000000 --- a/docs-devsite/firestore_lite.querysnapshot.md +++ /dev/null @@ -1,96 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QuerySnapshot class -A `QuerySnapshot` contains zero or more `DocumentSnapshot` objects representing the results of a query. The documents can be accessed as an array via the `docs` property or enumerated using the `forEach` method. The number of documents can be determined via the `empty` and `size` properties. - -Signature: - -```typescript -export declare class QuerySnapshot -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [docs](./firestore_lite.querysnapshot.md#querysnapshotdocs) | | Array<[QueryDocumentSnapshot](./firestore_lite.querydocumentsnapshot.md#querydocumentsnapshot_class)<T>> | An array of all the documents in the QuerySnapshot. | -| [empty](./firestore_lite.querysnapshot.md#querysnapshotempty) | | boolean | True if there are no documents in the QuerySnapshot. | -| [query](./firestore_lite.querysnapshot.md#querysnapshotquery) | | [Query](./firestore_lite.query.md#query_class)<T> | The query on which you called [getDocs()](./firestore_.md#getdocs) in order to get this QuerySnapshot. | -| [size](./firestore_lite.querysnapshot.md#querysnapshotsize) | | number | The number of documents in the QuerySnapshot. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [forEach(callback, thisArg)](./firestore_lite.querysnapshot.md#querysnapshotforeach) | | Enumerates all of the documents in the QuerySnapshot. | - -## QuerySnapshot.docs - -An array of all the documents in the `QuerySnapshot`. - -Signature: - -```typescript -get docs(): Array>; -``` - -## QuerySnapshot.empty - -True if there are no documents in the `QuerySnapshot`. - -Signature: - -```typescript -get empty(): boolean; -``` - -## QuerySnapshot.query - -The query on which you called [getDocs()](./firestore_.md#getdocs) in order to get this `QuerySnapshot`. - -Signature: - -```typescript -readonly query: Query; -``` - -## QuerySnapshot.size - -The number of documents in the `QuerySnapshot`. - -Signature: - -```typescript -get size(): number; -``` - -## QuerySnapshot.forEach() - -Enumerates all of the documents in the `QuerySnapshot`. - -Signature: - -```typescript -forEach(callback: (result: QueryDocumentSnapshot) => void, thisArg?: unknown): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| callback | (result: [QueryDocumentSnapshot](./firestore_lite.querydocumentsnapshot.md#querydocumentsnapshot_class)<T>) => void | A callback to be called with a QueryDocumentSnapshot for each document in the snapshot. | -| thisArg | unknown | The this binding for the callback. | - -Returns: - -void - diff --git a/docs-devsite/firestore_lite.settings.md b/docs-devsite/firestore_lite.settings.md deleted file mode 100644 index ae792a0fc6d..00000000000 --- a/docs-devsite/firestore_lite.settings.md +++ /dev/null @@ -1,57 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Settings interface -Specifies custom configurations for your Cloud Firestore instance. You must set these before invoking any other methods. - -Signature: - -```typescript -export declare interface Settings -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [host](./firestore_lite.settings.md#settingshost) | string | The hostname to connect to. | -| [ignoreUndefinedProperties](./firestore_lite.settings.md#settingsignoreundefinedproperties) | boolean | Whether to skip nested properties that are set to undefined during object serialization. If set to true, these properties are skipped and not written to Firestore. If set to false or omitted, the SDK throws an exception when it encounters properties of type undefined. | -| [ssl](./firestore_lite.settings.md#settingsssl) | boolean | Whether to use SSL when connecting. | - -## Settings.host - -The hostname to connect to. - -Signature: - -```typescript -host?: string; -``` - -## Settings.ignoreUndefinedProperties - -Whether to skip nested properties that are set to `undefined` during object serialization. If set to `true`, these properties are skipped and not written to Firestore. If set to `false` or omitted, the SDK throws an exception when it encounters properties of type `undefined`. - -Signature: - -```typescript -ignoreUndefinedProperties?: boolean; -``` - -## Settings.ssl - -Whether to use SSL when connecting. - -Signature: - -```typescript -ssl?: boolean; -``` diff --git a/docs-devsite/firestore_lite.timestamp.md b/docs-devsite/firestore_lite.timestamp.md deleted file mode 100644 index 7b18abc69db..00000000000 --- a/docs-devsite/firestore_lite.timestamp.md +++ /dev/null @@ -1,243 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Timestamp class -A `Timestamp` represents a point in time independent of any time zone or calendar, represented as seconds and fractions of seconds at nanosecond resolution in UTC Epoch time. - -It is encoded using the Proleptic Gregorian Calendar which extends the Gregorian calendar backwards to year one. It is encoded assuming all minutes are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. - -For examples and further specifications, refer to the [Timestamp definition](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto). - -Signature: - -```typescript -export declare class Timestamp -``` - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(seconds, nanoseconds)](./firestore_lite.timestamp.md#timestampconstructor) | | Creates a new timestamp. | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [nanoseconds](./firestore_lite.timestamp.md#timestampnanoseconds) | | number | The fractions of a second at nanosecond resolution.\* | -| [seconds](./firestore_lite.timestamp.md#timestampseconds) | | number | The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [fromDate(date)](./firestore_lite.timestamp.md#timestampfromdate) | static | Creates a new timestamp from the given date. | -| [fromMillis(milliseconds)](./firestore_lite.timestamp.md#timestampfrommillis) | static | Creates a new timestamp from the given number of milliseconds. | -| [isEqual(other)](./firestore_lite.timestamp.md#timestampisequal) | | Returns true if this Timestamp is equal to the provided one. | -| [now()](./firestore_lite.timestamp.md#timestampnow) | static | Creates a new timestamp with the current date, with millisecond precision. | -| [toDate()](./firestore_lite.timestamp.md#timestamptodate) | | Converts a Timestamp to a JavaScript Date object. This conversion causes a loss of precision since Date objects only support millisecond precision. | -| [toJSON()](./firestore_lite.timestamp.md#timestamptojson) | | Returns a JSON-serializable representation of this Timestamp. | -| [toMillis()](./firestore_lite.timestamp.md#timestamptomillis) | | Converts a Timestamp to a numeric timestamp (in milliseconds since epoch). This operation causes a loss of precision. | -| [toString()](./firestore_lite.timestamp.md#timestamptostring) | | Returns a textual representation of this Timestamp. | -| [valueOf()](./firestore_lite.timestamp.md#timestampvalueof) | | Converts this object to a primitive string, which allows Timestamp objects to be compared using the >, <=, >= and > operators. | - -## Timestamp.(constructor) - -Creates a new timestamp. - -Signature: - -```typescript -constructor( - seconds: number, - nanoseconds: number); -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| seconds | number | The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive. | -| nanoseconds | number | The non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanoseconds values that count forward in time. Must be from 0 to 999,999,999 inclusive. | - -## Timestamp.nanoseconds - -The fractions of a second at nanosecond resolution.\* - -Signature: - -```typescript -readonly nanoseconds: number; -``` - -## Timestamp.seconds - -The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. - -Signature: - -```typescript -readonly seconds: number; -``` - -## Timestamp.fromDate() - -Creates a new timestamp from the given date. - -Signature: - -```typescript -static fromDate(date: Date): Timestamp; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| date | Date | The date to initialize the Timestamp from. | - -Returns: - -[Timestamp](./firestore_lite.timestamp.md#timestamp_class) - -A new `Timestamp` representing the same point in time as the given date. - -## Timestamp.fromMillis() - -Creates a new timestamp from the given number of milliseconds. - -Signature: - -```typescript -static fromMillis(milliseconds: number): Timestamp; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| milliseconds | number | Number of milliseconds since Unix epoch 1970-01-01T00:00:00Z. | - -Returns: - -[Timestamp](./firestore_lite.timestamp.md#timestamp_class) - -A new `Timestamp` representing the same point in time as the given number of milliseconds. - -## Timestamp.isEqual() - -Returns true if this `Timestamp` is equal to the provided one. - -Signature: - -```typescript -isEqual(other: Timestamp): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| other | [Timestamp](./firestore_lite.timestamp.md#timestamp_class) | The Timestamp to compare against. | - -Returns: - -boolean - -true if this `Timestamp` is equal to the provided one. - -## Timestamp.now() - -Creates a new timestamp with the current date, with millisecond precision. - -Signature: - -```typescript -static now(): Timestamp; -``` -Returns: - -[Timestamp](./firestore_lite.timestamp.md#timestamp_class) - -a new timestamp representing the current date. - -## Timestamp.toDate() - -Converts a `Timestamp` to a JavaScript `Date` object. This conversion causes a loss of precision since `Date` objects only support millisecond precision. - -Signature: - -```typescript -toDate(): Date; -``` -Returns: - -Date - -JavaScript `Date` object representing the same point in time as this `Timestamp`, with millisecond precision. - -## Timestamp.toJSON() - -Returns a JSON-serializable representation of this `Timestamp`. - -Signature: - -```typescript -toJSON(): { - seconds: number; - nanoseconds: number; - }; -``` -Returns: - -{ seconds: number; nanoseconds: number; } - -## Timestamp.toMillis() - -Converts a `Timestamp` to a numeric timestamp (in milliseconds since epoch). This operation causes a loss of precision. - -Signature: - -```typescript -toMillis(): number; -``` -Returns: - -number - -The point in time corresponding to this timestamp, represented as the number of milliseconds since Unix epoch 1970-01-01T00:00:00Z. - -## Timestamp.toString() - -Returns a textual representation of this `Timestamp`. - -Signature: - -```typescript -toString(): string; -``` -Returns: - -string - -## Timestamp.valueOf() - -Converts this object to a primitive string, which allows `Timestamp` objects to be compared using the `>`, `<=`, `>=` and `>` operators. - -Signature: - -```typescript -valueOf(): string; -``` -Returns: - -string - diff --git a/docs-devsite/firestore_lite.transaction.md b/docs-devsite/firestore_lite.transaction.md deleted file mode 100644 index c643f08d66e..00000000000 --- a/docs-devsite/firestore_lite.transaction.md +++ /dev/null @@ -1,190 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Transaction class -A reference to a transaction. - -The `Transaction` object passed to a transaction's `updateFunction` provides the methods to read and write data within the transaction context. See [runTransaction()](./firestore_.md#runtransaction). - -Signature: - -```typescript -export declare class Transaction -``` - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [delete(documentRef)](./firestore_lite.transaction.md#transactiondelete) | | Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). | -| [get(documentRef)](./firestore_lite.transaction.md#transactionget) | | Reads the document referenced by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). | -| [set(documentRef, data)](./firestore_lite.transaction.md#transactionset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. | -| [set(documentRef, data, options)](./firestore_lite.transaction.md#transactionset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document. | -| [update(documentRef, data)](./firestore_lite.transaction.md#transactionupdate) | | Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. | -| [update(documentRef, field, value, moreFieldsAndValues)](./firestore_lite.transaction.md#transactionupdate) | | Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist.Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects. | - -## Transaction.delete() - -Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). - -Signature: - -```typescript -delete(documentRef: DocumentReference): this; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to the document to be deleted. | - -Returns: - -this - -This `Transaction` instance. Used for chaining method calls. - -## Transaction.get() - -Reads the document referenced by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). - -Signature: - -```typescript -get(documentRef: DocumentReference): Promise>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be read. | - -Returns: - -Promise<[DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<T>> - -A `DocumentSnapshot` with the read data. - -## Transaction.set() - -Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. - -Signature: - -```typescript -set(documentRef: DocumentReference, data: WithFieldValue): this; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | -| data | [WithFieldValue](./firestore_lite.md#withfieldvalue)<T> | An object of the fields and values for the document. | - -Returns: - -this - -This `Transaction` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not a valid Firestore document. - -## Transaction.set() - -Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. - -Signature: - -```typescript -set(documentRef: DocumentReference, data: PartialWithFieldValue, options: SetOptions): this; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | -| data | [PartialWithFieldValue](./firestore_lite.md#partialwithfieldvalue)<T> | An object of the fields and values for the document. | -| options | [SetOptions](./firestore_lite.md#setoptions) | An object to configure the set behavior. | - -Returns: - -this - -This `Transaction` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not a valid Firestore document. - -## Transaction.update() - -Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. - -Signature: - -```typescript -update(documentRef: DocumentReference, data: UpdateData): this; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be updated. | -| data | [UpdateData](./firestore_lite.md#updatedata)<T> | An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document. | - -Returns: - -this - -This `Transaction` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not valid Firestore data. - -## Transaction.update() - -Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. - -Nested fields can be updated by providing dot-separated field path strings or by providing `FieldPath` objects. - -Signature: - -```typescript -update(documentRef: DocumentReference, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): this; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to the document to be updated. | -| field | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The first field to update. | -| value | unknown | The first value. | -| moreFieldsAndValues | unknown\[\] | Additional key/value pairs. | - -Returns: - -this - -This `Transaction` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not valid Firestore data. - diff --git a/docs-devsite/firestore_lite.transactionoptions.md b/docs-devsite/firestore_lite.transactionoptions.md deleted file mode 100644 index 94941df172a..00000000000 --- a/docs-devsite/firestore_lite.transactionoptions.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# TransactionOptions interface -Options to customize transaction behavior. - -Signature: - -```typescript -export declare interface TransactionOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [maxAttempts](./firestore_lite.transactionoptions.md#transactionoptionsmaxattempts) | number | Maximum number of attempts to commit, after which transaction fails. Default is 5. | - -## TransactionOptions.maxAttempts - -Maximum number of attempts to commit, after which transaction fails. Default is 5. - -Signature: - -```typescript -readonly maxAttempts?: number; -``` diff --git a/docs-devsite/firestore_lite.writebatch.md b/docs-devsite/firestore_lite.writebatch.md deleted file mode 100644 index 141a99e8585..00000000000 --- a/docs-devsite/firestore_lite.writebatch.md +++ /dev/null @@ -1,181 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# WriteBatch class -A write batch, used to perform multiple writes as a single atomic unit. - -A `WriteBatch` object can be acquired by calling [writeBatch()](./firestore_.md#writebatch). It provides methods for adding writes to the write batch. None of the writes will be committed (or visible locally) until [WriteBatch.commit()](./firestore_.writebatch.md#writebatchcommit) is called. - -Signature: - -```typescript -export declare class WriteBatch -``` - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [commit()](./firestore_lite.writebatch.md#writebatchcommit) | | Commits all of the writes in this write batch as a single atomic unit.The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | -| [delete(documentRef)](./firestore_lite.writebatch.md#writebatchdelete) | | Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). | -| [set(documentRef, data)](./firestore_lite.writebatch.md#writebatchset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. | -| [set(documentRef, data, options)](./firestore_lite.writebatch.md#writebatchset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document. | -| [update(documentRef, data)](./firestore_lite.writebatch.md#writebatchupdate) | | Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. | -| [update(documentRef, field, value, moreFieldsAndValues)](./firestore_lite.writebatch.md#writebatchupdate) | | Updates fields in the document referred to by this [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist.Nested fields can be update by providing dot-separated field path strings or by providing FieldPath objects. | - -## WriteBatch.commit() - -Commits all of the writes in this write batch as a single atomic unit. - -The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. - -Signature: - -```typescript -commit(): Promise; -``` -Returns: - -Promise<void> - -A `Promise` resolved once all of the writes in the batch have been successfully written to the backend as an atomic unit (note that it won't resolve while you're offline). - -## WriteBatch.delete() - -Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). - -Signature: - -```typescript -delete(documentRef: DocumentReference): WriteBatch; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to the document to be deleted. | - -Returns: - -[WriteBatch](./firestore_lite.writebatch.md#writebatch_class) - -This `WriteBatch` instance. Used for chaining method calls. - -## WriteBatch.set() - -Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. - -Signature: - -```typescript -set(documentRef: DocumentReference, data: WithFieldValue): WriteBatch; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | -| data | [WithFieldValue](./firestore_lite.md#withfieldvalue)<T> | An object of the fields and values for the document. | - -Returns: - -[WriteBatch](./firestore_lite.writebatch.md#writebatch_class) - -This `WriteBatch` instance. Used for chaining method calls. - -## WriteBatch.set() - -Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. - -Signature: - -```typescript -set(documentRef: DocumentReference, data: PartialWithFieldValue, options: SetOptions): WriteBatch; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | -| data | [PartialWithFieldValue](./firestore_lite.md#partialwithfieldvalue)<T> | An object of the fields and values for the document. | -| options | [SetOptions](./firestore_lite.md#setoptions) | An object to configure the set behavior. | - -Returns: - -[WriteBatch](./firestore_lite.writebatch.md#writebatch_class) - -This `WriteBatch` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not a valid Firestore document. - -## WriteBatch.update() - -Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. - -Signature: - -```typescript -update(documentRef: DocumentReference, data: UpdateData): WriteBatch; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be updated. | -| data | [UpdateData](./firestore_lite.md#updatedata)<T> | An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document. | - -Returns: - -[WriteBatch](./firestore_lite.writebatch.md#writebatch_class) - -This `WriteBatch` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not valid Firestore data. - -## WriteBatch.update() - -Updates fields in the document referred to by this [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. - -Nested fields can be update by providing dot-separated field path strings or by providing `FieldPath` objects. - -Signature: - -```typescript -update(documentRef: DocumentReference, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): WriteBatch; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to the document to be updated. | -| field | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The first field to update. | -| value | unknown | The first value. | -| moreFieldsAndValues | unknown\[\] | Additional key value pairs. | - -Returns: - -[WriteBatch](./firestore_lite.writebatch.md#writebatch_class) - -This `WriteBatch` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not valid Firestore data. - diff --git a/docs-devsite/functions.functions.md b/docs-devsite/functions.functions.md deleted file mode 100644 index da5e0585f45..00000000000 --- a/docs-devsite/functions.functions.md +++ /dev/null @@ -1,57 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Functions interface -A `Functions` instance. - -Signature: - -```typescript -export interface Functions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [app](./functions.functions.md#functionsapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this Functions instance is associated with. | -| [customDomain](./functions.functions.md#functionscustomdomain) | string \| null | A custom domain hosting the callable Cloud Functions. ex: https://mydomain.com | -| [region](./functions.functions.md#functionsregion) | string | The region the callable Cloud Functions are located in. Default is us-central-1. | - -## Functions.app - -The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `Functions` instance is associated with. - -Signature: - -```typescript -app: FirebaseApp; -``` - -## Functions.customDomain - -A custom domain hosting the callable Cloud Functions. ex: https://mydomain.com - -Signature: - -```typescript -customDomain: string | null; -``` - -## Functions.region - -The region the callable Cloud Functions are located in. Default is `us-central-1`. - -Signature: - -```typescript -region: string; -``` diff --git a/docs-devsite/functions.functionserror.md b/docs-devsite/functions.functionserror.md deleted file mode 100644 index 3be96745b4c..00000000000 --- a/docs-devsite/functions.functionserror.md +++ /dev/null @@ -1,47 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FunctionsError interface -An error returned by the Firebase Functions client SDK. - -Signature: - -```typescript -export interface FunctionsError extends FirebaseError -``` -Extends: [FirebaseError](./util.firebaseerror.md#firebaseerror_class) - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [code](./functions.functionserror.md#functionserrorcode) | [FunctionsErrorCode](./functions.md#functionserrorcode) | A standard error code that will be returned to the client. This also determines the HTTP status code of the response, as defined in code.proto. | -| [details](./functions.functionserror.md#functionserrordetails) | unknown | Extra data to be converted to JSON and included in the error response. | - -## FunctionsError.code - -A standard error code that will be returned to the client. This also determines the HTTP status code of the response, as defined in code.proto. - -Signature: - -```typescript -readonly code: FunctionsErrorCode; -``` - -## FunctionsError.details - -Extra data to be converted to JSON and included in the error response. - -Signature: - -```typescript -readonly details?: unknown; -``` diff --git a/docs-devsite/functions.httpscallableoptions.md b/docs-devsite/functions.httpscallableoptions.md deleted file mode 100644 index cb84abf2526..00000000000 --- a/docs-devsite/functions.httpscallableoptions.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# HttpsCallableOptions interface -An interface for metadata about how calls should be executed. - -Signature: - -```typescript -export interface HttpsCallableOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [timeout](./functions.httpscallableoptions.md#httpscallableoptionstimeout) | number | Time in milliseconds after which to cancel if there is no response. Default is 70000. | - -## HttpsCallableOptions.timeout - -Time in milliseconds after which to cancel if there is no response. Default is 70000. - -Signature: - -```typescript -timeout?: number; -``` diff --git a/docs-devsite/functions.httpscallableresult.md b/docs-devsite/functions.httpscallableresult.md deleted file mode 100644 index 6c9877f423b..00000000000 --- a/docs-devsite/functions.httpscallableresult.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# HttpsCallableResult interface -An `HttpsCallableResult` wraps a single result from a function call. - -Signature: - -```typescript -export interface HttpsCallableResult -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [data](./functions.httpscallableresult.md#httpscallableresultdata) | ResponseData | Data returned from callable function. | - -## HttpsCallableResult.data - -Data returned from callable function. - -Signature: - -```typescript -readonly data: ResponseData; -``` diff --git a/docs-devsite/functions.md b/docs-devsite/functions.md deleted file mode 100644 index dd17ed38752..00000000000 --- a/docs-devsite/functions.md +++ /dev/null @@ -1,160 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# functions package -Cloud Functions for Firebase - -## Functions - -| Function | Description | -| --- | --- | -| [connectFunctionsEmulator(functionsInstance, host, port)](./functions.md#connectfunctionsemulator) | Modify this instance to communicate with the Cloud Functions emulator.Note: this must be called before this instance has been used to do any operations. | -| [getFunctions(app, regionOrCustomDomain)](./functions.md#getfunctions) | Returns a [Functions](./functions.functions.md#functions_interface) instance for the given app. | -| [httpsCallable(functionsInstance, name, options)](./functions.md#httpscallable) | Returns a reference to the callable HTTPS trigger with the given name. | -| [httpsCallableFromURL(functionsInstance, url, options)](./functions.md#httpscallablefromurl) | Returns a reference to the callable HTTPS trigger with the specified url. | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [Functions](./functions.functions.md#functions_interface) | A Functions instance. | -| [FunctionsError](./functions.functionserror.md#functionserror_interface) | An error returned by the Firebase Functions client SDK. | -| [HttpsCallableOptions](./functions.httpscallableoptions.md#httpscallableoptions_interface) | An interface for metadata about how calls should be executed. | -| [HttpsCallableResult](./functions.httpscallableresult.md#httpscallableresult_interface) | An HttpsCallableResult wraps a single result from a function call. | - -## Type Aliases - -| Type Alias | Description | -| --- | --- | -| [FunctionsErrorCode](./functions.md#functionserrorcode) | The set of Firebase Functions status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.mdPossible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (e.g. an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation. | -| [FunctionsErrorCodeCore](./functions.md#functionserrorcodecore) | Functions error code string appended after "functions/" product prefix. See [FunctionsErrorCode](./functions.md#functionserrorcode) for full documentation of codes. | -| [HttpsCallable](./functions.md#httpscallable) | A reference to a "callable" HTTP trigger in Google Cloud Functions. | - -## connectFunctionsEmulator() - -Modify this instance to communicate with the Cloud Functions emulator. - -Note: this must be called before this instance has been used to do any operations. - -Signature: - -```typescript -export declare function connectFunctionsEmulator(functionsInstance: Functions, host: string, port: number): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| functionsInstance | [Functions](./functions.functions.md#functions_interface) | | -| host | string | The emulator host (ex: localhost) | -| port | number | The emulator port (ex: 5001) | - -Returns: - -void - -## getFunctions() - -Returns a [Functions](./functions.functions.md#functions_interface) instance for the given app. - -Signature: - -```typescript -export declare function getFunctions(app?: FirebaseApp, regionOrCustomDomain?: string): Functions; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to use. | -| regionOrCustomDomain | string | one of: a) The region the callable functions are located in (ex: us-central1) b) A custom domain hosting the callable functions (ex: https://mydomain.com) | - -Returns: - -[Functions](./functions.functions.md#functions_interface) - -## httpsCallable() - -Returns a reference to the callable HTTPS trigger with the given name. - -Signature: - -```typescript -export declare function httpsCallable(functionsInstance: Functions, name: string, options?: HttpsCallableOptions): HttpsCallable; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| functionsInstance | [Functions](./functions.functions.md#functions_interface) | | -| name | string | The name of the trigger. | -| options | [HttpsCallableOptions](./functions.httpscallableoptions.md#httpscallableoptions_interface) | | - -Returns: - -[HttpsCallable](./functions.md#httpscallable)<RequestData, ResponseData> - -## httpsCallableFromURL() - -Returns a reference to the callable HTTPS trigger with the specified url. - -Signature: - -```typescript -export declare function httpsCallableFromURL(functionsInstance: Functions, url: string, options?: HttpsCallableOptions): HttpsCallable; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| functionsInstance | [Functions](./functions.functions.md#functions_interface) | | -| url | string | The url of the trigger. | -| options | [HttpsCallableOptions](./functions.httpscallableoptions.md#httpscallableoptions_interface) | | - -Returns: - -[HttpsCallable](./functions.md#httpscallable)<RequestData, ResponseData> - -## FunctionsErrorCode - -The set of Firebase Functions status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.md - -Possible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (e.g. an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation. - -Signature: - -```typescript -export declare type FunctionsErrorCode = `functions/${FunctionsErrorCodeCore}`; -``` - -## FunctionsErrorCodeCore - -Functions error code string appended after "functions/" product prefix. See [FunctionsErrorCode](./functions.md#functionserrorcode) for full documentation of codes. - -Signature: - -```typescript -export declare type FunctionsErrorCodeCore = 'ok' | 'cancelled' | 'unknown' | 'invalid-argument' | 'deadline-exceeded' | 'not-found' | 'already-exists' | 'permission-denied' | 'resource-exhausted' | 'failed-precondition' | 'aborted' | 'out-of-range' | 'unimplemented' | 'internal' | 'unavailable' | 'data-loss' | 'unauthenticated'; -``` - -## HttpsCallable - -A reference to a "callable" HTTP trigger in Google Cloud Functions. - -Signature: - -```typescript -export declare type HttpsCallable = (data?: RequestData | null) => Promise>; -``` diff --git a/docs-devsite/index.md b/docs-devsite/index.md deleted file mode 100644 index e19f70906ef..00000000000 --- a/docs-devsite/index.md +++ /dev/null @@ -1,30 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# API Reference - -## Packages - -| Package | Description | -| --- | --- | -| [@firebase/analytics](./analytics.md#analytics_package) | Firebase Analytics | -| [@firebase/app](./app.md#app_package) | Firebase App | -| [@firebase/app-check](./app-check.md#app-check_package) | Firebase App Check | -| [@firebase/auth](./auth.md#auth_package) | Firebase Authentication | -| [@firebase/database](./database.md#database_package) | Firebase Realtime Database | -| [@firebase/firestore](./firestore.md#firestore_package) | Cloud Firestore | -| [@firebase/functions](./functions.md#functions_package) | Cloud Functions for Firebase | -| [@firebase/installations](./installations.md#installations_package) | Firebase Installations | -| [@firebase/messaging](./messaging.md#messaging_package) | Firebase Cloud Messaging | -| [@firebase/performance](./performance.md#performance_package) | Firebase Performance Monitoring | -| [@firebase/remote-config](./remote-config.md#remote-config_package) | Firebase Remote Config | -| [@firebase/storage](./storage.md#storage_package) | Cloud Storage for Firebase | - diff --git a/docs-devsite/installations.installations.md b/docs-devsite/installations.installations.md deleted file mode 100644 index 4c1107e0354..00000000000 --- a/docs-devsite/installations.installations.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Installations interface -Public interface of the Firebase Installations SDK. - -Signature: - -```typescript -export interface Installations -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [app](./installations.installations.md#installationsapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this Installations instance is associated with. | - -## Installations.app - -The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `Installations` instance is associated with. - -Signature: - -```typescript -app: FirebaseApp; -``` diff --git a/docs-devsite/installations.md b/docs-devsite/installations.md deleted file mode 100644 index 0e234c6b7ed..00000000000 --- a/docs-devsite/installations.md +++ /dev/null @@ -1,160 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# installations package -Firebase Installations - -## Functions - -| Function | Description | -| --- | --- | -| [deleteInstallations(installations)](./installations.md#deleteinstallations) | Deletes the Firebase Installation and all associated data. | -| [getId(installations)](./installations.md#getid) | Creates a Firebase Installation if there isn't one for the app and returns the Installation ID. | -| [getInstallations(app)](./installations.md#getinstallations) | Returns an instance of [Installations](./installations.installations.md#installations_interface) associated with the given [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. | -| [getToken(installations, forceRefresh)](./installations.md#gettoken) | Returns a Firebase Installations auth token, identifying the current Firebase Installation. | -| [onIdChange(installations, callback)](./installations.md#onidchange) | Sets a new callback that will get called when Installation ID changes. Returns an unsubscribe function that will remove the callback when called. | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [Installations](./installations.installations.md#installations_interface) | Public interface of the Firebase Installations SDK. | - -## Type Aliases - -| Type Alias | Description | -| --- | --- | -| [IdChangeCallbackFn](./installations.md#idchangecallbackfn) | An user defined callback function that gets called when Installations ID changes. | -| [IdChangeUnsubscribeFn](./installations.md#idchangeunsubscribefn) | Unsubscribe a callback function previously added via [IdChangeCallbackFn](./installations.md#idchangecallbackfn). | - -## deleteInstallations() - -Deletes the Firebase Installation and all associated data. - -Signature: - -```typescript -export declare function deleteInstallations(installations: Installations): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| installations | [Installations](./installations.installations.md#installations_interface) | The Installations instance. | - -Returns: - -Promise<void> - -## getId() - -Creates a Firebase Installation if there isn't one for the app and returns the Installation ID. - -Signature: - -```typescript -export declare function getId(installations: Installations): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| installations | [Installations](./installations.installations.md#installations_interface) | The Installations instance. | - -Returns: - -Promise<string> - -## getInstallations() - -Returns an instance of [Installations](./installations.installations.md#installations_interface) associated with the given [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. - -Signature: - -```typescript -export declare function getInstallations(app?: FirebaseApp): Installations; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. | - -Returns: - -[Installations](./installations.installations.md#installations_interface) - -## getToken() - -Returns a Firebase Installations auth token, identifying the current Firebase Installation. - -Signature: - -```typescript -export declare function getToken(installations: Installations, forceRefresh?: boolean): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| installations | [Installations](./installations.installations.md#installations_interface) | The Installations instance. | -| forceRefresh | boolean | Force refresh regardless of token expiration. | - -Returns: - -Promise<string> - -## onIdChange() - -Sets a new callback that will get called when Installation ID changes. Returns an unsubscribe function that will remove the callback when called. - -Signature: - -```typescript -export declare function onIdChange(installations: Installations, callback: IdChangeCallbackFn): IdChangeUnsubscribeFn; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| installations | [Installations](./installations.installations.md#installations_interface) | The Installations instance. | -| callback | [IdChangeCallbackFn](./installations.md#idchangecallbackfn) | The callback function that is invoked when FID changes. | - -Returns: - -[IdChangeUnsubscribeFn](./installations.md#idchangeunsubscribefn) - -A function that can be called to unsubscribe. - -## IdChangeCallbackFn - -An user defined callback function that gets called when Installations ID changes. - -Signature: - -```typescript -export declare type IdChangeCallbackFn = (installationId: string) => void; -``` - -## IdChangeUnsubscribeFn - -Unsubscribe a callback function previously added via [IdChangeCallbackFn](./installations.md#idchangecallbackfn). - -Signature: - -```typescript -export declare type IdChangeUnsubscribeFn = () => void; -``` diff --git a/docs-devsite/messaging.md b/docs-devsite/messaging.md deleted file mode 100644 index ffbdd9ee3d8..00000000000 --- a/docs-devsite/messaging.md +++ /dev/null @@ -1,19 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# messaging package -Firebase Cloud Messaging - -| Entry Point | Description | -| --- | --- | -| [/](./messaging_.md#@firebase/messaging) | | -| [/sw](./messaging_sw.md#@firebase/messaging/sw) | | - diff --git a/docs-devsite/messaging_.fcmoptions.md b/docs-devsite/messaging_.fcmoptions.md deleted file mode 100644 index 15f6123bae2..00000000000 --- a/docs-devsite/messaging_.fcmoptions.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FcmOptions interface -Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) - -Signature: - -```typescript -export interface FcmOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [analyticsLabel](./messaging_.fcmoptions.md#fcmoptionsanalyticslabel) | string | The label associated with the message's analytics data. | -| [link](./messaging_.fcmoptions.md#fcmoptionslink) | string | The link to open when the user clicks on the notification. | - -## FcmOptions.analyticsLabel - -The label associated with the message's analytics data. - -Signature: - -```typescript -analyticsLabel?: string; -``` - -## FcmOptions.link - -The link to open when the user clicks on the notification. - -Signature: - -```typescript -link?: string; -``` diff --git a/docs-devsite/messaging_.gettokenoptions.md b/docs-devsite/messaging_.gettokenoptions.md deleted file mode 100644 index ed506fb5666..00000000000 --- a/docs-devsite/messaging_.gettokenoptions.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# GetTokenOptions interface -Options for [getToken()](./messaging_.md#gettoken) - -Signature: - -```typescript -export interface GetTokenOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [serviceWorkerRegistration](./messaging_.gettokenoptions.md#gettokenoptionsserviceworkerregistration) | ServiceWorkerRegistration | The service worker registration for receiving push messaging. If the registration is not provided explicitly, you need to have a firebase-messaging-sw.js at your root location. See [Retrieve the current registration token](https://firebase.google.com/docs/cloud-messaging/js/client#retrieve-the-current-registration-token) for more details. | -| [vapidKey](./messaging_.gettokenoptions.md#gettokenoptionsvapidkey) | string | The public server key provided to push services. It is used to authenticate the push subscribers to receive push messages only from sending servers that hold the corresponding private key. If it is not provided, a default VAPID key is used. Note that some push services (Chrome Push Service) require a non-default VAPID key. Therefore, it is recommended to generate and import a VAPID key for your project with [Configure Web Credentials with FCM](https://firebase.google.com/docs/cloud-messaging/js/client#configure_web_credentials_with_fcm). See [The Web Push Protocol](https://developers.google.com/web/fundamentals/push-notifications/web-push-protocol) for details on web push services. | - -## GetTokenOptions.serviceWorkerRegistration - -The service worker registration for receiving push messaging. If the registration is not provided explicitly, you need to have a `firebase-messaging-sw.js` at your root location. See [Retrieve the current registration token](https://firebase.google.com/docs/cloud-messaging/js/client#retrieve-the-current-registration-token) for more details. - -Signature: - -```typescript -serviceWorkerRegistration?: ServiceWorkerRegistration; -``` - -## GetTokenOptions.vapidKey - -The public server key provided to push services. It is used to authenticate the push subscribers to receive push messages only from sending servers that hold the corresponding private key. If it is not provided, a default VAPID key is used. Note that some push services (Chrome Push Service) require a non-default VAPID key. Therefore, it is recommended to generate and import a VAPID key for your project with [Configure Web Credentials with FCM](https://firebase.google.com/docs/cloud-messaging/js/client#configure_web_credentials_with_fcm). See [The Web Push Protocol](https://developers.google.com/web/fundamentals/push-notifications/web-push-protocol) for details on web push services. - -Signature: - -```typescript -vapidKey?: string; -``` diff --git a/docs-devsite/messaging_.md b/docs-devsite/messaging_.md deleted file mode 100644 index 71cd4a63608..00000000000 --- a/docs-devsite/messaging_.md +++ /dev/null @@ -1,140 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# @firebase/messaging - -## Functions - -| Function | Description | -| --- | --- | -| [deleteToken(messaging)](./messaging_.md#deletetoken) | Deletes the registration token associated with this [Messaging](./messaging_.messaging.md#messaging_interface) instance and unsubscribes the [Messaging](./messaging_.messaging.md#messaging_interface) instance from the push subscription. | -| [getMessaging(app)](./messaging_.md#getmessaging) | Retrieves a Firebase Cloud Messaging instance. | -| [getToken(messaging, options)](./messaging_.md#gettoken) | Subscribes the [Messaging](./messaging_.messaging.md#messaging_interface) instance to push notifications. Returns an Firebase Cloud Messaging registration token that can be used to send push messages to that [Messaging](./messaging_.messaging.md#messaging_interface) instance.If a notification permission isn't already granted, this method asks the user for permission. The returned promise rejects if the user does not allow the app to show notifications. | -| [isSupported()](./messaging_.md#issupported) | Checks if all required APIs exist in the browser. | -| [onMessage(messaging, nextOrObserver)](./messaging_.md#onmessage) | When a push message is received and the user is currently on a page for your origin, the message is passed to the page and an onMessage() event is dispatched with the payload of the push message. | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [FcmOptions](./messaging_.fcmoptions.md#fcmoptions_interface) | Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) | -| [GetTokenOptions](./messaging_.gettokenoptions.md#gettokenoptions_interface) | Options for [getToken()](./messaging_.md#gettoken) | -| [MessagePayload](./messaging_.messagepayload.md#messagepayload_interface) | Message payload that contains the notification payload that is represented with [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) and the data payload that contains an arbitrary number of key-value pairs sent by developers through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) | -| [Messaging](./messaging_.messaging.md#messaging_interface) | Public interface of the Firebase Cloud Messaging SDK. | -| [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) | Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) | - -## deleteToken() - -Deletes the registration token associated with this [Messaging](./messaging_.messaging.md#messaging_interface) instance and unsubscribes the [Messaging](./messaging_.messaging.md#messaging_interface) instance from the push subscription. - -Signature: - -```typescript -export declare function deleteToken(messaging: Messaging): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| messaging | [Messaging](./messaging_.messaging.md#messaging_interface) | The [Messaging](./messaging_.messaging.md#messaging_interface) instance. | - -Returns: - -Promise<boolean> - -The promise resolves when the token has been successfully deleted. - -## getMessaging() - -Retrieves a Firebase Cloud Messaging instance. - -Signature: - -```typescript -export declare function getMessagingInWindow(app?: FirebaseApp): Messaging; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | | - -Returns: - -[Messaging](./messaging_.messaging.md#messaging_interface) - -The Firebase Cloud Messaging instance associated with the provided firebase app. - -## getToken() - -Subscribes the [Messaging](./messaging_.messaging.md#messaging_interface) instance to push notifications. Returns an Firebase Cloud Messaging registration token that can be used to send push messages to that [Messaging](./messaging_.messaging.md#messaging_interface) instance. - -If a notification permission isn't already granted, this method asks the user for permission. The returned promise rejects if the user does not allow the app to show notifications. - -Signature: - -```typescript -export declare function getToken(messaging: Messaging, options?: GetTokenOptions): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| messaging | [Messaging](./messaging_.messaging.md#messaging_interface) | The [Messaging](./messaging_.messaging.md#messaging_interface) instance. | -| options | [GetTokenOptions](./messaging_.gettokenoptions.md#gettokenoptions_interface) | Provides an optional vapid key and an optinoal service worker registration | - -Returns: - -Promise<string> - -The promise resolves with an FCM registration token. - -## isSupported() - -Checks if all required APIs exist in the browser. - -Signature: - -```typescript -export declare function isWindowSupported(): Promise; -``` -Returns: - -Promise<boolean> - -a Promise that resolves to a boolean. - -## onMessage() - -When a push message is received and the user is currently on a page for your origin, the message is passed to the page and an `onMessage()` event is dispatched with the payload of the push message. - -Signature: - -```typescript -export declare function onMessage(messaging: Messaging, nextOrObserver: NextFn | Observer): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| messaging | [Messaging](./messaging_.messaging.md#messaging_interface) | The [Messaging](./messaging_.messaging.md#messaging_interface) instance. | -| nextOrObserver | [NextFn](./util.md#nextfn)<[MessagePayload](./messaging_.messagepayload.md#messagepayload_interface)> \| [Observer](./util.observer.md#observer_interface)<[MessagePayload](./messaging_.messagepayload.md#messagepayload_interface)> | This function, or observer object with next defined, is called when a message is received and the user is currently viewing your page. | - -Returns: - -[Unsubscribe](./util.md#unsubscribe) - -To stop listening for messages execute this returned function. - diff --git a/docs-devsite/messaging_.messagepayload.md b/docs-devsite/messaging_.messagepayload.md deleted file mode 100644 index 1a944ebbc52..00000000000 --- a/docs-devsite/messaging_.messagepayload.md +++ /dev/null @@ -1,92 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# MessagePayload interface -Message payload that contains the notification payload that is represented with [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) and the data payload that contains an arbitrary number of key-value pairs sent by developers through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) - -Signature: - -```typescript -export interface MessagePayload -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [collapseKey](./messaging_.messagepayload.md#messagepayloadcollapsekey) | string | The collapse key of the message. See [Non-collapsible and collapsible messages](https://firebase.google.com/docs/cloud-messaging/concept-options#collapsible_and_non-collapsible_messages) | -| [data](./messaging_.messagepayload.md#messagepayloaddata) | { \[key: string\]: string; } | Arbitrary key/value payload. | -| [fcmOptions](./messaging_.messagepayload.md#messagepayloadfcmoptions) | [FcmOptions](./messaging_.fcmoptions.md#fcmoptions_interface) | Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) | -| [from](./messaging_.messagepayload.md#messagepayloadfrom) | string | The sender of this message. | -| [messageId](./messaging_.messagepayload.md#messagepayloadmessageid) | string | The message id of a message. | -| [notification](./messaging_.messagepayload.md#messagepayloadnotification) | [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) | Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) | - -## MessagePayload.collapseKey - -The collapse key of the message. See [Non-collapsible and collapsible messages](https://firebase.google.com/docs/cloud-messaging/concept-options#collapsible_and_non-collapsible_messages) - -Signature: - -```typescript -collapseKey: string; -``` - -## MessagePayload.data - -Arbitrary key/value payload. - -Signature: - -```typescript -data?: { - [key: string]: string; - }; -``` - -## MessagePayload.fcmOptions - -Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) - -Signature: - -```typescript -fcmOptions?: FcmOptions; -``` - -## MessagePayload.from - -The sender of this message. - -Signature: - -```typescript -from: string; -``` - -## MessagePayload.messageId - -The message id of a message. - -Signature: - -```typescript -messageId: string; -``` - -## MessagePayload.notification - -Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) - -Signature: - -```typescript -notification?: NotificationPayload; -``` diff --git a/docs-devsite/messaging_.messaging.md b/docs-devsite/messaging_.messaging.md deleted file mode 100644 index 8d16b75467a..00000000000 --- a/docs-devsite/messaging_.messaging.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Messaging interface -Public interface of the Firebase Cloud Messaging SDK. - -Signature: - -```typescript -export interface Messaging -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [app](./messaging_.messaging.md#messagingapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this Messaging instance is associated with. | - -## Messaging.app - -The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `Messaging` instance is associated with. - -Signature: - -```typescript -app: FirebaseApp; -``` diff --git a/docs-devsite/messaging_.notificationpayload.md b/docs-devsite/messaging_.notificationpayload.md deleted file mode 100644 index c063d346787..00000000000 --- a/docs-devsite/messaging_.notificationpayload.md +++ /dev/null @@ -1,57 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# NotificationPayload interface -Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) - -Signature: - -```typescript -export interface NotificationPayload -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [body](./messaging_.notificationpayload.md#notificationpayloadbody) | string | The notification's body text. | -| [image](./messaging_.notificationpayload.md#notificationpayloadimage) | string | The URL of an image that is downloaded on the device and displayed in the notification. | -| [title](./messaging_.notificationpayload.md#notificationpayloadtitle) | string | The notification's title. | - -## NotificationPayload.body - -The notification's body text. - -Signature: - -```typescript -body?: string; -``` - -## NotificationPayload.image - -The URL of an image that is downloaded on the device and displayed in the notification. - -Signature: - -```typescript -image?: string; -``` - -## NotificationPayload.title - -The notification's title. - -Signature: - -```typescript -title?: string; -``` diff --git a/docs-devsite/messaging_sw.fcmoptions.md b/docs-devsite/messaging_sw.fcmoptions.md deleted file mode 100644 index 55fdddaa0e3..00000000000 --- a/docs-devsite/messaging_sw.fcmoptions.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FcmOptions interface -Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) - -Signature: - -```typescript -export interface FcmOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [analyticsLabel](./messaging_sw.fcmoptions.md#fcmoptionsanalyticslabel) | string | The label associated with the message's analytics data. | -| [link](./messaging_sw.fcmoptions.md#fcmoptionslink) | string | The link to open when the user clicks on the notification. | - -## FcmOptions.analyticsLabel - -The label associated with the message's analytics data. - -Signature: - -```typescript -analyticsLabel?: string; -``` - -## FcmOptions.link - -The link to open when the user clicks on the notification. - -Signature: - -```typescript -link?: string; -``` diff --git a/docs-devsite/messaging_sw.gettokenoptions.md b/docs-devsite/messaging_sw.gettokenoptions.md deleted file mode 100644 index 5e724513a02..00000000000 --- a/docs-devsite/messaging_sw.gettokenoptions.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# GetTokenOptions interface -Options for [getToken()](./messaging_.md#gettoken) - -Signature: - -```typescript -export interface GetTokenOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [serviceWorkerRegistration](./messaging_sw.gettokenoptions.md#gettokenoptionsserviceworkerregistration) | ServiceWorkerRegistration | The service worker registration for receiving push messaging. If the registration is not provided explicitly, you need to have a firebase-messaging-sw.js at your root location. See [Retrieve the current registration token](https://firebase.google.com/docs/cloud-messaging/js/client#retrieve-the-current-registration-token) for more details. | -| [vapidKey](./messaging_sw.gettokenoptions.md#gettokenoptionsvapidkey) | string | The public server key provided to push services. It is used to authenticate the push subscribers to receive push messages only from sending servers that hold the corresponding private key. If it is not provided, a default VAPID key is used. Note that some push services (Chrome Push Service) require a non-default VAPID key. Therefore, it is recommended to generate and import a VAPID key for your project with [Configure Web Credentials with FCM](https://firebase.google.com/docs/cloud-messaging/js/client#configure_web_credentials_with_fcm). See [The Web Push Protocol](https://developers.google.com/web/fundamentals/push-notifications/web-push-protocol) for details on web push services. | - -## GetTokenOptions.serviceWorkerRegistration - -The service worker registration for receiving push messaging. If the registration is not provided explicitly, you need to have a `firebase-messaging-sw.js` at your root location. See [Retrieve the current registration token](https://firebase.google.com/docs/cloud-messaging/js/client#retrieve-the-current-registration-token) for more details. - -Signature: - -```typescript -serviceWorkerRegistration?: ServiceWorkerRegistration; -``` - -## GetTokenOptions.vapidKey - -The public server key provided to push services. It is used to authenticate the push subscribers to receive push messages only from sending servers that hold the corresponding private key. If it is not provided, a default VAPID key is used. Note that some push services (Chrome Push Service) require a non-default VAPID key. Therefore, it is recommended to generate and import a VAPID key for your project with [Configure Web Credentials with FCM](https://firebase.google.com/docs/cloud-messaging/js/client#configure_web_credentials_with_fcm). See [The Web Push Protocol](https://developers.google.com/web/fundamentals/push-notifications/web-push-protocol) for details on web push services. - -Signature: - -```typescript -vapidKey?: string; -``` diff --git a/docs-devsite/messaging_sw.md b/docs-devsite/messaging_sw.md deleted file mode 100644 index 4b183b00e9a..00000000000 --- a/docs-devsite/messaging_sw.md +++ /dev/null @@ -1,113 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# @firebase/messaging/sw - -## Functions - -| Function | Description | -| --- | --- | -| [experimentalSetDeliveryMetricsExportedToBigQueryEnabled(messaging, enable)](./messaging_sw.md#experimentalsetdeliverymetricsexportedtobigqueryenabled) | Enables or disables Firebase Cloud Messaging message delivery metrics export to BigQuery. By default, message delivery metrics are not exported to BigQuery. Use this method to enable or disable the export at runtime. | -| [getMessaging(app)](./messaging_sw.md#getmessaging) | Retrieves a Firebase Cloud Messaging instance. | -| [isSupported()](./messaging_sw.md#issupported) | Checks whether all required APIs exist within SW Context | -| [onBackgroundMessage(messaging, nextOrObserver)](./messaging_sw.md#onbackgroundmessage) | Called when a message is received while the app is in the background. An app is considered to be in the background if no active window is displayed. | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [FcmOptions](./messaging_sw.fcmoptions.md#fcmoptions_interface) | Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) | -| [GetTokenOptions](./messaging_sw.gettokenoptions.md#gettokenoptions_interface) | Options for [getToken()](./messaging_.md#gettoken) | -| [MessagePayload](./messaging_sw.messagepayload.md#messagepayload_interface) | Message payload that contains the notification payload that is represented with [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) and the data payload that contains an arbitrary number of key-value pairs sent by developers through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) | -| [Messaging](./messaging_sw.messaging.md#messaging_interface) | Public interface of the Firebase Cloud Messaging SDK. | -| [NotificationPayload](./messaging_sw.notificationpayload.md#notificationpayload_interface) | Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) | - -## experimentalSetDeliveryMetricsExportedToBigQueryEnabled() - -Enables or disables Firebase Cloud Messaging message delivery metrics export to BigQuery. By default, message delivery metrics are not exported to BigQuery. Use this method to enable or disable the export at runtime. - -Signature: - -```typescript -export declare function experimentalSetDeliveryMetricsExportedToBigQueryEnabled(messaging: Messaging, enable: boolean): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| messaging | [Messaging](./messaging_.messaging.md#messaging_interface) | The FirebaseMessaging instance. | -| enable | boolean | Whether Firebase Cloud Messaging should export message delivery metrics to BigQuery. | - -Returns: - -void - -## getMessaging() - -Retrieves a Firebase Cloud Messaging instance. - -Signature: - -```typescript -export declare function getMessagingInSw(app?: FirebaseApp): Messaging; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | | - -Returns: - -[Messaging](./messaging_.messaging.md#messaging_interface) - -The Firebase Cloud Messaging instance associated with the provided firebase app. - -## isSupported() - -Checks whether all required APIs exist within SW Context - -Signature: - -```typescript -export declare function isSwSupported(): Promise; -``` -Returns: - -Promise<boolean> - -a Promise that resolves to a boolean. - -## onBackgroundMessage() - -Called when a message is received while the app is in the background. An app is considered to be in the background if no active window is displayed. - -Signature: - -```typescript -export declare function onBackgroundMessage(messaging: Messaging, nextOrObserver: NextFn | Observer): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| messaging | [Messaging](./messaging_.messaging.md#messaging_interface) | The [Messaging](./messaging_.messaging.md#messaging_interface) instance. | -| nextOrObserver | [NextFn](./util.md#nextfn)<[MessagePayload](./messaging_.messagepayload.md#messagepayload_interface)> \| [Observer](./util.observer.md#observer_interface)<[MessagePayload](./messaging_.messagepayload.md#messagepayload_interface)> | This function, or observer object with next defined, is called when a message is received and the app is currently in the background. | - -Returns: - -[Unsubscribe](./util.md#unsubscribe) - -To stop listening for messages execute this returned function - diff --git a/docs-devsite/messaging_sw.messagepayload.md b/docs-devsite/messaging_sw.messagepayload.md deleted file mode 100644 index 2037bb0016d..00000000000 --- a/docs-devsite/messaging_sw.messagepayload.md +++ /dev/null @@ -1,92 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# MessagePayload interface -Message payload that contains the notification payload that is represented with [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) and the data payload that contains an arbitrary number of key-value pairs sent by developers through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) - -Signature: - -```typescript -export interface MessagePayload -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [collapseKey](./messaging_sw.messagepayload.md#messagepayloadcollapsekey) | string | The collapse key of the message. See [Non-collapsible and collapsible messages](https://firebase.google.com/docs/cloud-messaging/concept-options#collapsible_and_non-collapsible_messages) | -| [data](./messaging_sw.messagepayload.md#messagepayloaddata) | { \[key: string\]: string; } | Arbitrary key/value payload. | -| [fcmOptions](./messaging_sw.messagepayload.md#messagepayloadfcmoptions) | [FcmOptions](./messaging_.fcmoptions.md#fcmoptions_interface) | Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) | -| [from](./messaging_sw.messagepayload.md#messagepayloadfrom) | string | The sender of this message. | -| [messageId](./messaging_sw.messagepayload.md#messagepayloadmessageid) | string | The message id of a message. | -| [notification](./messaging_sw.messagepayload.md#messagepayloadnotification) | [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) | Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) | - -## MessagePayload.collapseKey - -The collapse key of the message. See [Non-collapsible and collapsible messages](https://firebase.google.com/docs/cloud-messaging/concept-options#collapsible_and_non-collapsible_messages) - -Signature: - -```typescript -collapseKey: string; -``` - -## MessagePayload.data - -Arbitrary key/value payload. - -Signature: - -```typescript -data?: { - [key: string]: string; - }; -``` - -## MessagePayload.fcmOptions - -Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) - -Signature: - -```typescript -fcmOptions?: FcmOptions; -``` - -## MessagePayload.from - -The sender of this message. - -Signature: - -```typescript -from: string; -``` - -## MessagePayload.messageId - -The message id of a message. - -Signature: - -```typescript -messageId: string; -``` - -## MessagePayload.notification - -Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) - -Signature: - -```typescript -notification?: NotificationPayload; -``` diff --git a/docs-devsite/messaging_sw.messaging.md b/docs-devsite/messaging_sw.messaging.md deleted file mode 100644 index cfd15fe9aaf..00000000000 --- a/docs-devsite/messaging_sw.messaging.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Messaging interface -Public interface of the Firebase Cloud Messaging SDK. - -Signature: - -```typescript -export interface Messaging -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [app](./messaging_sw.messaging.md#messagingapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this Messaging instance is associated with. | - -## Messaging.app - -The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `Messaging` instance is associated with. - -Signature: - -```typescript -app: FirebaseApp; -``` diff --git a/docs-devsite/messaging_sw.notificationpayload.md b/docs-devsite/messaging_sw.notificationpayload.md deleted file mode 100644 index e4ac4e73f66..00000000000 --- a/docs-devsite/messaging_sw.notificationpayload.md +++ /dev/null @@ -1,57 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# NotificationPayload interface -Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) - -Signature: - -```typescript -export interface NotificationPayload -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [body](./messaging_sw.notificationpayload.md#notificationpayloadbody) | string | The notification's body text. | -| [image](./messaging_sw.notificationpayload.md#notificationpayloadimage) | string | The URL of an image that is downloaded on the device and displayed in the notification. | -| [title](./messaging_sw.notificationpayload.md#notificationpayloadtitle) | string | The notification's title. | - -## NotificationPayload.body - -The notification's body text. - -Signature: - -```typescript -body?: string; -``` - -## NotificationPayload.image - -The URL of an image that is downloaded on the device and displayed in the notification. - -Signature: - -```typescript -image?: string; -``` - -## NotificationPayload.title - -The notification's title. - -Signature: - -```typescript -title?: string; -``` diff --git a/docs-devsite/performance.firebaseperformance.md b/docs-devsite/performance.firebaseperformance.md deleted file mode 100644 index d8aea429952..00000000000 --- a/docs-devsite/performance.firebaseperformance.md +++ /dev/null @@ -1,57 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FirebasePerformance interface -The Firebase Performance Monitoring service interface. - -Signature: - -```typescript -export interface FirebasePerformance -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [app](./performance.firebaseperformance.md#firebaseperformanceapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this FirebasePerformance instance is associated with. | -| [dataCollectionEnabled](./performance.firebaseperformance.md#firebaseperformancedatacollectionenabled) | boolean | Controls the logging of custom traces. | -| [instrumentationEnabled](./performance.firebaseperformance.md#firebaseperformanceinstrumentationenabled) | boolean | Controls the logging of automatic traces and HTTP/S network monitoring. | - -## FirebasePerformance.app - -The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `FirebasePerformance` instance is associated with. - -Signature: - -```typescript -app: FirebaseApp; -``` - -## FirebasePerformance.dataCollectionEnabled - -Controls the logging of custom traces. - -Signature: - -```typescript -dataCollectionEnabled: boolean; -``` - -## FirebasePerformance.instrumentationEnabled - -Controls the logging of automatic traces and HTTP/S network monitoring. - -Signature: - -```typescript -instrumentationEnabled: boolean; -``` diff --git a/docs-devsite/performance.md b/docs-devsite/performance.md deleted file mode 100644 index bcc2ce5c836..00000000000 --- a/docs-devsite/performance.md +++ /dev/null @@ -1,92 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# performance package -Firebase Performance Monitoring - -## Functions - -| Function | Description | -| --- | --- | -| [getPerformance(app)](./performance.md#getperformance) | Returns a [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) instance for the given app. | -| [initializePerformance(app, settings)](./performance.md#initializeperformance) | Returns a [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) instance for the given app. Can only be called once. | -| [trace(performance, name)](./performance.md#trace) | Returns a new PerformanceTrace instance. | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) | The Firebase Performance Monitoring service interface. | -| [PerformanceSettings](./performance.performancesettings.md#performancesettings_interface) | Defines configuration options for the Performance Monitoring SDK. | -| [PerformanceTrace](./performance.performancetrace.md#performancetrace_interface) | The interface representing a Trace. | - -## getPerformance() - -Returns a [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) instance for the given app. - -Signature: - -```typescript -export declare function getPerformance(app?: FirebaseApp): FirebasePerformance; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to use. | - -Returns: - -[FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) - -## initializePerformance() - -Returns a [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) instance for the given app. Can only be called once. - -Signature: - -```typescript -export declare function initializePerformance(app: FirebaseApp, settings?: PerformanceSettings): FirebasePerformance; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to use. | -| settings | [PerformanceSettings](./performance.performancesettings.md#performancesettings_interface) | Optional settings for the [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) instance. | - -Returns: - -[FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) - -## trace() - -Returns a new `PerformanceTrace` instance. - -Signature: - -```typescript -export declare function trace(performance: FirebasePerformance, name: string): PerformanceTrace; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| performance | [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) | The [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) instance to use. | -| name | string | The name of the trace. | - -Returns: - -[PerformanceTrace](./performance.performancetrace.md#performancetrace_interface) - diff --git a/docs-devsite/performance.performancesettings.md b/docs-devsite/performance.performancesettings.md deleted file mode 100644 index 9d85a96ce6a..00000000000 --- a/docs-devsite/performance.performancesettings.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# PerformanceSettings interface -Defines configuration options for the Performance Monitoring SDK. - -Signature: - -```typescript -export interface PerformanceSettings -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [dataCollectionEnabled](./performance.performancesettings.md#performancesettingsdatacollectionenabled) | boolean | Whether to collect custom events. | -| [instrumentationEnabled](./performance.performancesettings.md#performancesettingsinstrumentationenabled) | boolean | Whether to collect out of the box events. | - -## PerformanceSettings.dataCollectionEnabled - -Whether to collect custom events. - -Signature: - -```typescript -dataCollectionEnabled?: boolean; -``` - -## PerformanceSettings.instrumentationEnabled - -Whether to collect out of the box events. - -Signature: - -```typescript -instrumentationEnabled?: boolean; -``` diff --git a/docs-devsite/performance.performancetrace.md b/docs-devsite/performance.performancetrace.md deleted file mode 100644 index ffda20476da..00000000000 --- a/docs-devsite/performance.performancetrace.md +++ /dev/null @@ -1,228 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# PerformanceTrace interface -The interface representing a `Trace`. - -Signature: - -```typescript -export interface PerformanceTrace -``` - -## Methods - -| Method | Description | -| --- | --- | -| [getAttribute(attr)](./performance.performancetrace.md#performancetracegetattribute) | Retrieves the value which a custom attribute is set to. | -| [getAttributes()](./performance.performancetrace.md#performancetracegetattributes) | Returns a map of all custom attributes of a trace instance. | -| [getMetric(metricName)](./performance.performancetrace.md#performancetracegetmetric) | Returns the value of the custom metric by that name. If a custom metric with that name does not exist will return zero. | -| [incrementMetric(metricName, num)](./performance.performancetrace.md#performancetraceincrementmetric) | Adds to the value of a custom metric. If a custom metric with the provided name does not exist, it creates one with that name and the value equal to the given number. The value will be floored down to an integer. | -| [putAttribute(attr, value)](./performance.performancetrace.md#performancetraceputattribute) | Set a custom attribute of a trace to a certain value. | -| [putMetric(metricName, num)](./performance.performancetrace.md#performancetraceputmetric) | Sets the value of the specified custom metric to the given number regardless of whether a metric with that name already exists on the trace instance or not. The value will be floored down to an integer. | -| [record(startTime, duration, options)](./performance.performancetrace.md#performancetracerecord) | Records a trace from given parameters. This provides a direct way to use trace without a need to start/stop. This is useful for use cases in which the trace cannot directly be used (e.g. if the duration was captured before the Performance SDK was loaded). | -| [removeAttribute(attr)](./performance.performancetrace.md#performancetraceremoveattribute) | Removes the specified custom attribute from a trace instance. | -| [start()](./performance.performancetrace.md#performancetracestart) | Starts the timing for the trace instance. | -| [stop()](./performance.performancetrace.md#performancetracestop) | Stops the timing of the trace instance and logs the data of the instance. | - -## PerformanceTrace.getAttribute() - -Retrieves the value which a custom attribute is set to. - -Signature: - -```typescript -getAttribute(attr: string): string | undefined; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| attr | string | Name of the custom attribute. | - -Returns: - -string \| undefined - -## PerformanceTrace.getAttributes() - -Returns a map of all custom attributes of a trace instance. - -Signature: - -```typescript -getAttributes(): { - [key: string]: string; - }; -``` -Returns: - -{ \[key: string\]: string; } - -## PerformanceTrace.getMetric() - -Returns the value of the custom metric by that name. If a custom metric with that name does not exist will return zero. - -Signature: - -```typescript -getMetric(metricName: string): number; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| metricName | string | Name of the custom metric. | - -Returns: - -number - -## PerformanceTrace.incrementMetric() - -Adds to the value of a custom metric. If a custom metric with the provided name does not exist, it creates one with that name and the value equal to the given number. The value will be floored down to an integer. - -Signature: - -```typescript -incrementMetric(metricName: string, num?: number): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| metricName | string | The name of the custom metric. | -| num | number | The number to be added to the value of the custom metric. If not provided, it uses a default value of one. | - -Returns: - -void - -## PerformanceTrace.putAttribute() - -Set a custom attribute of a trace to a certain value. - -Signature: - -```typescript -putAttribute(attr: string, value: string): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| attr | string | Name of the custom attribute. | -| value | string | Value of the custom attribute. | - -Returns: - -void - -## PerformanceTrace.putMetric() - -Sets the value of the specified custom metric to the given number regardless of whether a metric with that name already exists on the trace instance or not. The value will be floored down to an integer. - -Signature: - -```typescript -putMetric(metricName: string, num: number): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| metricName | string | Name of the custom metric. | -| num | number | Value to of the custom metric. | - -Returns: - -void - -## PerformanceTrace.record() - -Records a trace from given parameters. This provides a direct way to use trace without a need to start/stop. This is useful for use cases in which the trace cannot directly be used (e.g. if the duration was captured before the Performance SDK was loaded). - -Signature: - -```typescript -record(startTime: number, duration: number, options?: { - metrics?: { - [key: string]: number; - }; - attributes?: { - [key: string]: string; - }; - }): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| startTime | number | trace start time since epoch in millisec. | -| duration | number | The duraction of the trace in millisec. | -| options | { metrics?: { \[key: string\]: number; }; attributes?: { \[key: string\]: string; }; } | An object which can optionally hold maps of custom metrics and custom attributes. | - -Returns: - -void - -## PerformanceTrace.removeAttribute() - -Removes the specified custom attribute from a trace instance. - -Signature: - -```typescript -removeAttribute(attr: string): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| attr | string | Name of the custom attribute. | - -Returns: - -void - -## PerformanceTrace.start() - -Starts the timing for the trace instance. - -Signature: - -```typescript -start(): void; -``` -Returns: - -void - -## PerformanceTrace.stop() - -Stops the timing of the trace instance and logs the data of the instance. - -Signature: - -```typescript -stop(): void; -``` -Returns: - -void - diff --git a/docs-devsite/remote-config.md b/docs-devsite/remote-config.md deleted file mode 100644 index e192d093d7b..00000000000 --- a/docs-devsite/remote-config.md +++ /dev/null @@ -1,342 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# remote-config package -Firebase Remote Config - -## Functions - -| Function | Description | -| --- | --- | -| [activate(remoteConfig)](./remote-config.md#activate) | Makes the last fetched config available to the getters. | -| [ensureInitialized(remoteConfig)](./remote-config.md#ensureinitialized) | Ensures the last activated config are available to the getters. | -| [fetchAndActivate(remoteConfig)](./remote-config.md#fetchandactivate) | Performs fetch and activate operations, as a convenience. | -| [fetchConfig(remoteConfig)](./remote-config.md#fetchconfig) | Fetches and caches configuration from the Remote Config service. | -| [getAll(remoteConfig)](./remote-config.md#getall) | Gets all config. | -| [getBoolean(remoteConfig, key)](./remote-config.md#getboolean) | Gets the value for the given key as a boolean.Convenience method for calling remoteConfig.getValue(key).asBoolean(). | -| [getNumber(remoteConfig, key)](./remote-config.md#getnumber) | Gets the value for the given key as a number.Convenience method for calling remoteConfig.getValue(key).asNumber(). | -| [getRemoteConfig(app)](./remote-config.md#getremoteconfig) | | -| [getString(remoteConfig, key)](./remote-config.md#getstring) | Gets the value for the given key as a string. Convenience method for calling remoteConfig.getValue(key).asString(). | -| [getValue(remoteConfig, key)](./remote-config.md#getvalue) | Gets the [Value](./remote-config.value.md#value_interface) for the given key. | -| [isSupported()](./remote-config.md#issupported) | This method provides two different checks:1. Check if IndexedDB exists in the browser environment. 2. Check if the current browser context allows IndexedDB open() calls. | -| [setLogLevel(remoteConfig, logLevel)](./remote-config.md#setloglevel) | Defines the log level to use. | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The Firebase Remote Config service interface. | -| [RemoteConfigSettings](./remote-config.remoteconfigsettings.md#remoteconfigsettings_interface) | Defines configuration options for the Remote Config SDK. | -| [Value](./remote-config.value.md#value_interface) | Wraps a value with metadata and type-safe getters. | - -## Type Aliases - -| Type Alias | Description | -| --- | --- | -| [FetchStatus](./remote-config.md#fetchstatus) | Summarizes the outcome of the last attempt to fetch config from the Firebase Remote Config server.
  • "no-fetch-yet" indicates the [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance has not yet attempted to fetch config, or that SDK initialization is incomplete.
  • "success" indicates the last attempt succeeded.
  • "failure" indicates the last attempt failed.
  • "throttle" indicates the last attempt was rate-limited.
| -| [LogLevel](./remote-config.md#loglevel) | Defines levels of Remote Config logging. | -| [ValueSource](./remote-config.md#valuesource) | Indicates the source of a value.
  • "static" indicates the value was defined by a static constant.
  • "default" indicates the value was defined by default config.
  • "remote" indicates the value was defined by fetched config.
| - -## activate() - -Makes the last fetched config available to the getters. - -Signature: - -```typescript -export declare function activate(remoteConfig: RemoteConfig): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | - -Returns: - -Promise<boolean> - -A `Promise` which resolves to true if the current call activated the fetched configs. If the fetched configs were already activated, the `Promise` will resolve to false. - -## ensureInitialized() - -Ensures the last activated config are available to the getters. - -Signature: - -```typescript -export declare function ensureInitialized(remoteConfig: RemoteConfig): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | - -Returns: - -Promise<void> - -A `Promise` that resolves when the last activated config is available to the getters. - -## fetchAndActivate() - -Performs fetch and activate operations, as a convenience. - -Signature: - -```typescript -export declare function fetchAndActivate(remoteConfig: RemoteConfig): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | - -Returns: - -Promise<boolean> - -A `Promise` which resolves to true if the current call activated the fetched configs. If the fetched configs were already activated, the `Promise` will resolve to false. - -## fetchConfig() - -Fetches and caches configuration from the Remote Config service. - -Signature: - -```typescript -export declare function fetchConfig(remoteConfig: RemoteConfig): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | - -Returns: - -Promise<void> - -## getAll() - -Gets all config. - -Signature: - -```typescript -export declare function getAll(remoteConfig: RemoteConfig): Record; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | - -Returns: - -Record<string, [Value](./remote-config.value.md#value_interface)> - -All config. - -## getBoolean() - -Gets the value for the given key as a boolean. - -Convenience method for calling remoteConfig.getValue(key).asBoolean(). - -Signature: - -```typescript -export declare function getBoolean(remoteConfig: RemoteConfig, key: string): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | -| key | string | The name of the parameter. | - -Returns: - -boolean - -The value for the given key as a boolean. - -## getNumber() - -Gets the value for the given key as a number. - -Convenience method for calling remoteConfig.getValue(key).asNumber(). - -Signature: - -```typescript -export declare function getNumber(remoteConfig: RemoteConfig, key: string): number; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | -| key | string | The name of the parameter. | - -Returns: - -number - -The value for the given key as a number. - -## getRemoteConfig() - -Signature: - -```typescript -export declare function getRemoteConfig(app?: FirebaseApp): RemoteConfig; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. | - -Returns: - -[RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) - -A [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. - -## getString() - -Gets the value for the given key as a string. Convenience method for calling remoteConfig.getValue(key).asString(). - -Signature: - -```typescript -export declare function getString(remoteConfig: RemoteConfig, key: string): string; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | -| key | string | The name of the parameter. | - -Returns: - -string - -The value for the given key as a string. - -## getValue() - -Gets the [Value](./remote-config.value.md#value_interface) for the given key. - -Signature: - -```typescript -export declare function getValue(remoteConfig: RemoteConfig, key: string): Value; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | -| key | string | The name of the parameter. | - -Returns: - -[Value](./remote-config.value.md#value_interface) - -The value for the given key. - -## isSupported() - -This method provides two different checks: - -1. Check if IndexedDB exists in the browser environment. 2. Check if the current browser context allows IndexedDB `open()` calls. - -Signature: - -```typescript -export declare function isSupported(): Promise; -``` -Returns: - -Promise<boolean> - -A `Promise` which resolves to true if a [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance can be initialized in this environment, or false if it cannot. - -## setLogLevel() - -Defines the log level to use. - -Signature: - -```typescript -export declare function setLogLevel(remoteConfig: RemoteConfig, logLevel: RemoteConfigLogLevel): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | -| logLevel | [RemoteConfigLogLevel](./remote-config.md#loglevel) | The log level to set. | - -Returns: - -void - -## FetchStatus - -Summarizes the outcome of the last attempt to fetch config from the Firebase Remote Config server. - -
  • "no-fetch-yet" indicates the [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance has not yet attempted to fetch config, or that SDK initialization is incomplete.
  • "success" indicates the last attempt succeeded.
  • "failure" indicates the last attempt failed.
  • "throttle" indicates the last attempt was rate-limited.
- -Signature: - -```typescript -export declare type FetchStatus = 'no-fetch-yet' | 'success' | 'failure' | 'throttle'; -``` - -## LogLevel - -Defines levels of Remote Config logging. - -Signature: - -```typescript -export declare type LogLevel = 'debug' | 'error' | 'silent'; -``` - -## ValueSource - -Indicates the source of a value. - -
  • "static" indicates the value was defined by a static constant.
  • "default" indicates the value was defined by default config.
  • "remote" indicates the value was defined by fetched config.
- -Signature: - -```typescript -export declare type ValueSource = 'static' | 'default' | 'remote'; -``` diff --git a/docs-devsite/remote-config.remoteconfig.md b/docs-devsite/remote-config.remoteconfig.md deleted file mode 100644 index 3f4f0688b13..00000000000 --- a/docs-devsite/remote-config.remoteconfig.md +++ /dev/null @@ -1,81 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# RemoteConfig interface -The Firebase Remote Config service interface. - -Signature: - -```typescript -export interface RemoteConfig -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [app](./remote-config.remoteconfig.md#remoteconfigapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this RemoteConfig instance is associated with. | -| [defaultConfig](./remote-config.remoteconfig.md#remoteconfigdefaultconfig) | { \[key: string\]: string \| number \| boolean; } | Object containing default values for configs. | -| [fetchTimeMillis](./remote-config.remoteconfig.md#remoteconfigfetchtimemillis) | number | The Unix timestamp in milliseconds of the last successful fetch, or negative one if the [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance either hasn't fetched or initialization is incomplete. | -| [lastFetchStatus](./remote-config.remoteconfig.md#remoteconfiglastfetchstatus) | [FetchStatus](./remote-config.md#fetchstatus) | The status of the last fetch attempt. | -| [settings](./remote-config.remoteconfig.md#remoteconfigsettings) | [RemoteConfigSettings](./remote-config.remoteconfigsettings.md#remoteconfigsettings_interface) | Defines configuration for the Remote Config SDK. | - -## RemoteConfig.app - -The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `RemoteConfig` instance is associated with. - -Signature: - -```typescript -app: FirebaseApp; -``` - -## RemoteConfig.defaultConfig - -Object containing default values for configs. - -Signature: - -```typescript -defaultConfig: { - [key: string]: string | number | boolean; - }; -``` - -## RemoteConfig.fetchTimeMillis - -The Unix timestamp in milliseconds of the last successful fetch, or negative one if the [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance either hasn't fetched or initialization is incomplete. - -Signature: - -```typescript -fetchTimeMillis: number; -``` - -## RemoteConfig.lastFetchStatus - -The status of the last fetch attempt. - -Signature: - -```typescript -lastFetchStatus: FetchStatus; -``` - -## RemoteConfig.settings - -Defines configuration for the Remote Config SDK. - -Signature: - -```typescript -settings: RemoteConfigSettings; -``` diff --git a/docs-devsite/remote-config.remoteconfigsettings.md b/docs-devsite/remote-config.remoteconfigsettings.md deleted file mode 100644 index 58e505ad863..00000000000 --- a/docs-devsite/remote-config.remoteconfigsettings.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# RemoteConfigSettings interface -Defines configuration options for the Remote Config SDK. - -Signature: - -```typescript -export interface RemoteConfigSettings -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [fetchTimeoutMillis](./remote-config.remoteconfigsettings.md#remoteconfigsettingsfetchtimeoutmillis) | number | Defines the maximum amount of milliseconds to wait for a response when fetching configuration from the Remote Config server. Defaults to 60000 (One minute). | -| [minimumFetchIntervalMillis](./remote-config.remoteconfigsettings.md#remoteconfigsettingsminimumfetchintervalmillis) | number | Defines the maximum age in milliseconds of an entry in the config cache before it is considered stale. Defaults to 43200000 (Twelve hours). | - -## RemoteConfigSettings.fetchTimeoutMillis - -Defines the maximum amount of milliseconds to wait for a response when fetching configuration from the Remote Config server. Defaults to 60000 (One minute). - -Signature: - -```typescript -fetchTimeoutMillis: number; -``` - -## RemoteConfigSettings.minimumFetchIntervalMillis - -Defines the maximum age in milliseconds of an entry in the config cache before it is considered stale. Defaults to 43200000 (Twelve hours). - -Signature: - -```typescript -minimumFetchIntervalMillis: number; -``` diff --git a/docs-devsite/remote-config.value.md b/docs-devsite/remote-config.value.md deleted file mode 100644 index 36fb492d524..00000000000 --- a/docs-devsite/remote-config.value.md +++ /dev/null @@ -1,83 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Value interface -Wraps a value with metadata and type-safe getters. - -Signature: - -```typescript -export interface Value -``` - -## Methods - -| Method | Description | -| --- | --- | -| [asBoolean()](./remote-config.value.md#valueasboolean) | Gets the value as a boolean.The following values (case insensitive) are interpreted as true: "1", "true", "t", "yes", "y", "on". Other values are interpreted as false. | -| [asNumber()](./remote-config.value.md#valueasnumber) | Gets the value as a number. Comparable to calling Number(value) \|\| 0. | -| [asString()](./remote-config.value.md#valueasstring) | Gets the value as a string. | -| [getSource()](./remote-config.value.md#valuegetsource) | Gets the [ValueSource](./remote-config.md#valuesource) for the given key. | - -## Value.asBoolean() - -Gets the value as a boolean. - -The following values (case insensitive) are interpreted as true: "1", "true", "t", "yes", "y", "on". Other values are interpreted as false. - -Signature: - -```typescript -asBoolean(): boolean; -``` -Returns: - -boolean - -## Value.asNumber() - -Gets the value as a number. Comparable to calling Number(value) \|\| 0. - -Signature: - -```typescript -asNumber(): number; -``` -Returns: - -number - -## Value.asString() - -Gets the value as a string. - -Signature: - -```typescript -asString(): string; -``` -Returns: - -string - -## Value.getSource() - -Gets the [ValueSource](./remote-config.md#valuesource) for the given key. - -Signature: - -```typescript -getSource(): ValueSource; -``` -Returns: - -[ValueSource](./remote-config.md#valuesource) - diff --git a/docs-devsite/storage.firebasestorage.md b/docs-devsite/storage.firebasestorage.md deleted file mode 100644 index a44df8bfc3d..00000000000 --- a/docs-devsite/storage.firebasestorage.md +++ /dev/null @@ -1,58 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FirebaseStorage interface -A Firebase Storage instance. - -Signature: - -```typescript -export interface FirebaseStorage extends _FirebaseService -``` -Extends: \_FirebaseService - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [app](./storage.firebasestorage.md#firebasestorageapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this FirebaseStorage instance. | -| [maxOperationRetryTime](./storage.firebasestorage.md#firebasestoragemaxoperationretrytime) | number | The maximum time to retry operations other than uploads or downloads in milliseconds. | -| [maxUploadRetryTime](./storage.firebasestorage.md#firebasestoragemaxuploadretrytime) | number | The maximum time to retry uploads in milliseconds. | - -## FirebaseStorage.app - -The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this `FirebaseStorage` instance. - -Signature: - -```typescript -readonly app: FirebaseApp; -``` - -## FirebaseStorage.maxOperationRetryTime - -The maximum time to retry operations other than uploads or downloads in milliseconds. - -Signature: - -```typescript -maxOperationRetryTime: number; -``` - -## FirebaseStorage.maxUploadRetryTime - -The maximum time to retry uploads in milliseconds. - -Signature: - -```typescript -maxUploadRetryTime: number; -``` diff --git a/docs-devsite/storage.fullmetadata.md b/docs-devsite/storage.fullmetadata.md deleted file mode 100644 index ca8d66e08d5..00000000000 --- a/docs-devsite/storage.fullmetadata.md +++ /dev/null @@ -1,135 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FullMetadata interface -The full set of object metadata, including read-only properties. - -Signature: - -```typescript -export interface FullMetadata extends UploadMetadata -``` -Extends: [UploadMetadata](./storage.uploadmetadata.md#uploadmetadata_interface) - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [bucket](./storage.fullmetadata.md#fullmetadatabucket) | string | The bucket this object is contained in. | -| [downloadTokens](./storage.fullmetadata.md#fullmetadatadownloadtokens) | string\[\] \| undefined | Tokens to allow access to the downloatd URL. | -| [fullPath](./storage.fullmetadata.md#fullmetadatafullpath) | string | The full path of this object. | -| [generation](./storage.fullmetadata.md#fullmetadatageneration) | string | The object's generation. [https://cloud.google.com/storage/docs/metadata\#generation-number](https://cloud.google.com/storage/docs/metadata#generation-number) | -| [metageneration](./storage.fullmetadata.md#fullmetadatametageneration) | string | The object's metageneration. [https://cloud.google.com/storage/docs/metadata\#generation-number](https://cloud.google.com/storage/docs/metadata#generation-number) | -| [name](./storage.fullmetadata.md#fullmetadataname) | string | The short name of this object, which is the last component of the full path. For example, if fullPath is 'full/path/image.png', name is 'image.png'. | -| [ref](./storage.fullmetadata.md#fullmetadataref) | [StorageReference](./storage.storagereference.md#storagereference_interface) \| undefined | StorageReference associated with this upload. | -| [size](./storage.fullmetadata.md#fullmetadatasize) | number | The size of this object, in bytes. | -| [timeCreated](./storage.fullmetadata.md#fullmetadatatimecreated) | string | A date string representing when this object was created. | -| [updated](./storage.fullmetadata.md#fullmetadataupdated) | string | A date string representing when this object was last updated. | - -## FullMetadata.bucket - -The bucket this object is contained in. - -Signature: - -```typescript -bucket: string; -``` - -## FullMetadata.downloadTokens - -Tokens to allow access to the downloatd URL. - -Signature: - -```typescript -downloadTokens: string[] | undefined; -``` - -## FullMetadata.fullPath - -The full path of this object. - -Signature: - -```typescript -fullPath: string; -``` - -## FullMetadata.generation - -The object's generation. [https://cloud.google.com/storage/docs/metadata\#generation-number](https://cloud.google.com/storage/docs/metadata#generation-number) - -Signature: - -```typescript -generation: string; -``` - -## FullMetadata.metageneration - -The object's metageneration. [https://cloud.google.com/storage/docs/metadata\#generation-number](https://cloud.google.com/storage/docs/metadata#generation-number) - -Signature: - -```typescript -metageneration: string; -``` - -## FullMetadata.name - -The short name of this object, which is the last component of the full path. For example, if fullPath is 'full/path/image.png', name is 'image.png'. - -Signature: - -```typescript -name: string; -``` - -## FullMetadata.ref - -`StorageReference` associated with this upload. - -Signature: - -```typescript -ref?: StorageReference | undefined; -``` - -## FullMetadata.size - -The size of this object, in bytes. - -Signature: - -```typescript -size: number; -``` - -## FullMetadata.timeCreated - -A date string representing when this object was created. - -Signature: - -```typescript -timeCreated: string; -``` - -## FullMetadata.updated - -A date string representing when this object was last updated. - -Signature: - -```typescript -updated: string; -``` diff --git a/docs-devsite/storage.listoptions.md b/docs-devsite/storage.listoptions.md deleted file mode 100644 index 3f2e92bc639..00000000000 --- a/docs-devsite/storage.listoptions.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ListOptions interface -The options `list()` accepts. - -Signature: - -```typescript -export interface ListOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [maxResults](./storage.listoptions.md#listoptionsmaxresults) | number \| null | If set, limits the total number of prefixes and items to return. The default and maximum maxResults is 1000. | -| [pageToken](./storage.listoptions.md#listoptionspagetoken) | string \| null | The nextPageToken from a previous call to list(). If provided, listing is resumed from the previous position. | - -## ListOptions.maxResults - -If set, limits the total number of `prefixes` and `items` to return. The default and maximum maxResults is 1000. - -Signature: - -```typescript -maxResults?: number | null; -``` - -## ListOptions.pageToken - -The `nextPageToken` from a previous call to `list()`. If provided, listing is resumed from the previous position. - -Signature: - -```typescript -pageToken?: string | null; -``` diff --git a/docs-devsite/storage.listresult.md b/docs-devsite/storage.listresult.md deleted file mode 100644 index b53a61d92db..00000000000 --- a/docs-devsite/storage.listresult.md +++ /dev/null @@ -1,59 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ListResult interface -Result returned by list(). - -Signature: - -```typescript -export interface ListResult -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [items](./storage.listresult.md#listresultitems) | [StorageReference](./storage.storagereference.md#storagereference_interface)\[\] | Objects in this directory. You can call getMetadata() and getDownloadUrl() on them. | -| [nextPageToken](./storage.listresult.md#listresultnextpagetoken) | string | If set, there might be more results for this list. Use this token to resume the list. | -| [prefixes](./storage.listresult.md#listresultprefixes) | [StorageReference](./storage.storagereference.md#storagereference_interface)\[\] | References to prefixes (sub-folders). You can call list() on them to get its contents.Folders are implicit based on '/' in the object paths. For example, if a bucket has two objects '/a/b/1' and '/a/b/2', list('/a') will return '/a/b' as a prefix. | - -## ListResult.items - -Objects in this directory. You can call getMetadata() and getDownloadUrl() on them. - -Signature: - -```typescript -items: StorageReference[]; -``` - -## ListResult.nextPageToken - -If set, there might be more results for this list. Use this token to resume the list. - -Signature: - -```typescript -nextPageToken?: string; -``` - -## ListResult.prefixes - -References to prefixes (sub-folders). You can call list() on them to get its contents. - -Folders are implicit based on '/' in the object paths. For example, if a bucket has two objects '/a/b/1' and '/a/b/2', list('/a') will return '/a/b' as a prefix. - -Signature: - -```typescript -prefixes: StorageReference[]; -``` diff --git a/docs-devsite/storage.md b/docs-devsite/storage.md deleted file mode 100644 index dc92633ec0d..00000000000 --- a/docs-devsite/storage.md +++ /dev/null @@ -1,494 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# storage package -Cloud Storage for Firebase - -## Functions - -| Function | Description | -| --- | --- | -| [connectStorageEmulator(storage, host, port, options)](./storage.md#connectstorageemulator) | Modify this [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance to communicate with the Cloud Storage emulator. | -| [deleteObject(ref)](./storage.md#deleteobject) | Deletes the object at this location. | -| [getBlob(ref, maxDownloadSizeBytes)](./storage.md#getblob) | Downloads the data at the object's location. Returns an error if the object is not found.To use this functionality, you have to whitelist your app's origin in your Cloud Storage bucket. See also https://cloud.google.com/storage/docs/configuring-corsThis API is not available in Node. | -| [getBytes(ref, maxDownloadSizeBytes)](./storage.md#getbytes) | Downloads the data at the object's location. Returns an error if the object is not found.To use this functionality, you have to whitelist your app's origin in your Cloud Storage bucket. See also https://cloud.google.com/storage/docs/configuring-cors | -| [getDownloadURL(ref)](./storage.md#getdownloadurl) | Returns the download URL for the given [StorageReference](./storage.storagereference.md#storagereference_interface). | -| [getMetadata(ref)](./storage.md#getmetadata) | A Promise that resolves with the metadata for this object. If this object doesn't exist or metadata cannot be retreived, the promise is rejected. | -| [getStorage(app, bucketUrl)](./storage.md#getstorage) | Gets a [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance for the given Firebase app. | -| [getStream(ref, maxDownloadSizeBytes)](./storage.md#getstream) | Downloads the data at the object's location. Raises an error event if the object is not found.This API is only available in Node. | -| [list(ref, options)](./storage.md#list) | List items (files) and prefixes (folders) under this storage reference.List API is only available for Firebase Rules Version 2.GCS is a key-blob store. Firebase Storage imposes the semantic of '/' delimited folder structure. Refer to GCS's List API if you want to learn more.To adhere to Firebase Rules's Semantics, Firebase Storage does not support objects whose paths end with "/" or contain two consecutive "/"s. Firebase Storage List API will filter these unsupported objects. list() may fail if there are too many unsupported objects in the bucket. | -| [listAll(ref)](./storage.md#listall) | List all items (files) and prefixes (folders) under this storage reference.This is a helper method for calling list() repeatedly until there are no more results. The default pagination size is 1000.Note: The results may not be consistent if objects are changed while this operation is running.Warning: listAll may potentially consume too many resources if there are too many results. | -| [ref(storage, url)](./storage.md#ref) | Returns a [StorageReference](./storage.storagereference.md#storagereference_interface) for the given url. | -| [ref(storageOrRef, path)](./storage.md#ref) | Returns a [StorageReference](./storage.storagereference.md#storagereference_interface) for the given path in the default bucket. | -| [updateMetadata(ref, metadata)](./storage.md#updatemetadata) | Updates the metadata for this object. | -| [uploadBytes(ref, data, metadata)](./storage.md#uploadbytes) | Uploads data to this object's location. The upload is not resumable. | -| [uploadBytesResumable(ref, data, metadata)](./storage.md#uploadbytesresumable) | Uploads data to this object's location. The upload can be paused and resumed, and exposes progress updates. | -| [uploadString(ref, value, format, metadata)](./storage.md#uploadstring) | Uploads a string to this object's location. The upload is not resumable. | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) | A Firebase Storage instance. | -| [FullMetadata](./storage.fullmetadata.md#fullmetadata_interface) | The full set of object metadata, including read-only properties. | -| [ListOptions](./storage.listoptions.md#listoptions_interface) | The options list() accepts. | -| [ListResult](./storage.listresult.md#listresult_interface) | Result returned by list(). | -| [SettableMetadata](./storage.settablemetadata.md#settablemetadata_interface) | Object metadata that can be set at any time. | -| [StorageError](./storage.storageerror.md#storageerror_interface) | An error returned by the Firebase Storage SDK. | -| [StorageObserver](./storage.storageobserver.md#storageobserver_interface) | A stream observer for Firebase Storage. | -| [StorageReference](./storage.storagereference.md#storagereference_interface) | Represents a reference to a Google Cloud Storage object. Developers can upload, download, and delete objects, as well as get/set object metadata. | -| [UploadMetadata](./storage.uploadmetadata.md#uploadmetadata_interface) | Object metadata that can be set at upload. | -| [UploadResult](./storage.uploadresult.md#uploadresult_interface) | Result returned from a non-resumable upload. | -| [UploadTask](./storage.uploadtask.md#uploadtask_interface) | Represents the process of uploading an object. Allows you to monitor and manage the upload. | -| [UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface) | Holds data about the current state of the upload task. | - -## Variables - -| Variable | Description | -| --- | --- | -| [StringFormat](./storage.md#stringformat) | An enumeration of the possible string formats for upload. | - -## Type Aliases - -| Type Alias | Description | -| --- | --- | -| [StringFormat](./storage.md#stringformat) | An enumeration of the possible string formats for upload. | -| [TaskEvent](./storage.md#taskevent) | An event that is triggered on a task. | -| [TaskState](./storage.md#taskstate) | Represents the current state of a running upload. | - -## connectStorageEmulator() - -Modify this [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance to communicate with the Cloud Storage emulator. - -Signature: - -```typescript -export declare function connectStorageEmulator(storage: FirebaseStorage, host: string, port: number, options?: { - mockUserToken?: EmulatorMockTokenOptions | string; -}): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| storage | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) | The [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance | -| host | string | The emulator host (ex: localhost) | -| port | number | The emulator port (ex: 5001) | -| options | { mockUserToken?: [EmulatorMockTokenOptions](./util.md#emulatormocktokenoptions) \| string; } | Emulator options. options.mockUserToken is the mock auth token to use for unit testing Security Rules. | - -Returns: - -void - -## deleteObject() - -Deletes the object at this location. - -Signature: - -```typescript -export declare function deleteObject(ref: StorageReference): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) for object to delete. | - -Returns: - -Promise<void> - -A `Promise` that resolves if the deletion succeeds. - -## getBlob() - -Downloads the data at the object's location. Returns an error if the object is not found. - -To use this functionality, you have to whitelist your app's origin in your Cloud Storage bucket. See also https://cloud.google.com/storage/docs/configuring-cors - -This API is not available in Node. - -Signature: - -```typescript -export declare function getBlob(ref: StorageReference, maxDownloadSizeBytes?: number): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | StorageReference where data should be downloaded. | -| maxDownloadSizeBytes | number | If set, the maximum allowed size in bytes to retrieve. | - -Returns: - -Promise<Blob> - -A Promise that resolves with a Blob containing the object's bytes - -## getBytes() - -Downloads the data at the object's location. Returns an error if the object is not found. - -To use this functionality, you have to whitelist your app's origin in your Cloud Storage bucket. See also https://cloud.google.com/storage/docs/configuring-cors - -Signature: - -```typescript -export declare function getBytes(ref: StorageReference, maxDownloadSizeBytes?: number): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | StorageReference where data should be downloaded. | -| maxDownloadSizeBytes | number | If set, the maximum allowed size in bytes to retrieve. | - -Returns: - -Promise<ArrayBuffer> - -A Promise containing the object's bytes - -## getDownloadURL() - -Returns the download URL for the given [StorageReference](./storage.storagereference.md#storagereference_interface). - -Signature: - -```typescript -export declare function getDownloadURL(ref: StorageReference): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) to get the download URL for. | - -Returns: - -Promise<string> - -A `Promise` that resolves with the download URL for this object. - -## getMetadata() - -A `Promise` that resolves with the metadata for this object. If this object doesn't exist or metadata cannot be retreived, the promise is rejected. - -Signature: - -```typescript -export declare function getMetadata(ref: StorageReference): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) to get metadata from. | - -Returns: - -Promise<[FullMetadata](./storage.fullmetadata.md#fullmetadata_interface)> - -## getStorage() - -Gets a [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance for the given Firebase app. - -Signature: - -```typescript -export declare function getStorage(app?: FirebaseApp, bucketUrl?: string): FirebaseStorage; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | Firebase app to get [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance for. | -| bucketUrl | string | The gs:// url to your Firebase Storage Bucket. If not passed, uses the app's default Storage Bucket. | - -Returns: - -[FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) - -A [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance. - -## getStream() - -Downloads the data at the object's location. Raises an error event if the object is not found. - -This API is only available in Node. - -Signature: - -```typescript -export declare function getStream(ref: StorageReference, maxDownloadSizeBytes?: number): NodeJS.ReadableStream; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | StorageReference where data should be downloaded. | -| maxDownloadSizeBytes | number | If set, the maximum allowed size in bytes to retrieve. | - -Returns: - -NodeJS.ReadableStream - -A stream with the object's data as bytes - -## list() - -List items (files) and prefixes (folders) under this storage reference. - -List API is only available for Firebase Rules Version 2. - -GCS is a key-blob store. Firebase Storage imposes the semantic of '/' delimited folder structure. Refer to GCS's List API if you want to learn more. - -To adhere to Firebase Rules's Semantics, Firebase Storage does not support objects whose paths end with "/" or contain two consecutive "/"s. Firebase Storage List API will filter these unsupported objects. list() may fail if there are too many unsupported objects in the bucket. - -Signature: - -```typescript -export declare function list(ref: StorageReference, options?: ListOptions): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) to get list from. | -| options | [ListOptions](./storage.listoptions.md#listoptions_interface) | See [ListOptions](./storage.listoptions.md#listoptions_interface) for details. | - -Returns: - -Promise<[ListResult](./storage.listresult.md#listresult_interface)> - -A `Promise` that resolves with the items and prefixes. `prefixes` contains references to sub-folders and `items` contains references to objects in this folder. `nextPageToken` can be used to get the rest of the results. - -## listAll() - -List all items (files) and prefixes (folders) under this storage reference. - -This is a helper method for calling list() repeatedly until there are no more results. The default pagination size is 1000. - -Note: The results may not be consistent if objects are changed while this operation is running. - -Warning: `listAll` may potentially consume too many resources if there are too many results. - -Signature: - -```typescript -export declare function listAll(ref: StorageReference): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) to get list from. | - -Returns: - -Promise<[ListResult](./storage.listresult.md#listresult_interface)> - -A `Promise` that resolves with all the items and prefixes under the current storage reference. `prefixes` contains references to sub-directories and `items` contains references to objects in this folder. `nextPageToken` is never returned. - -## ref() - -Returns a [StorageReference](./storage.storagereference.md#storagereference_interface) for the given url. - -Signature: - -```typescript -export declare function ref(storage: FirebaseStorage, url?: string): StorageReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| storage | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance. | -| url | string | URL. If empty, returns root reference. | - -Returns: - -[StorageReference](./storage.storagereference.md#storagereference_interface) - -## ref() - -Returns a [StorageReference](./storage.storagereference.md#storagereference_interface) for the given path in the default bucket. - -Signature: - -```typescript -export declare function ref(storageOrRef: FirebaseStorage | StorageReference, path?: string): StorageReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| storageOrRef | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) \| [StorageReference](./storage.storagereference.md#storagereference_interface) | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) or [StorageReference](./storage.storagereference.md#storagereference_interface). | -| path | string | | - -Returns: - -[StorageReference](./storage.storagereference.md#storagereference_interface) - -## updateMetadata() - -Updates the metadata for this object. - -Signature: - -```typescript -export declare function updateMetadata(ref: StorageReference, metadata: SettableMetadata): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) to update metadata for. | -| metadata | [SettableMetadata](./storage.settablemetadata.md#settablemetadata_interface) | The new metadata for the object. Only values that have been explicitly set will be changed. Explicitly setting a value to null will remove the metadata. | - -Returns: - -Promise<[FullMetadata](./storage.fullmetadata.md#fullmetadata_interface)> - -A `Promise` that resolves with the new metadata for this object. - -## uploadBytes() - -Uploads data to this object's location. The upload is not resumable. - -Signature: - -```typescript -export declare function uploadBytes(ref: StorageReference, data: Blob | Uint8Array | ArrayBuffer, metadata?: UploadMetadata): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) where data should be uploaded. | -| data | Blob \| Uint8Array \| ArrayBuffer | The data to upload. | -| metadata | [UploadMetadata](./storage.uploadmetadata.md#uploadmetadata_interface) | Metadata for the data to upload. | - -Returns: - -Promise<[UploadResult](./storage.uploadresult.md#uploadresult_interface)> - -A Promise containing an UploadResult - -## uploadBytesResumable() - -Uploads data to this object's location. The upload can be paused and resumed, and exposes progress updates. - -Signature: - -```typescript -export declare function uploadBytesResumable(ref: StorageReference, data: Blob | Uint8Array | ArrayBuffer, metadata?: UploadMetadata): UploadTask; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) where data should be uploaded. | -| data | Blob \| Uint8Array \| ArrayBuffer | The data to upload. | -| metadata | [UploadMetadata](./storage.uploadmetadata.md#uploadmetadata_interface) | Metadata for the data to upload. | - -Returns: - -[UploadTask](./storage.uploadtask.md#uploadtask_interface) - -An UploadTask - -## uploadString() - -Uploads a string to this object's location. The upload is not resumable. - -Signature: - -```typescript -export declare function uploadString(ref: StorageReference, value: string, format?: StringFormat, metadata?: UploadMetadata): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) where string should be uploaded. | -| value | string | The string to upload. | -| format | [StringFormat](./storage.md#stringformat) | The format of the string to upload. | -| metadata | [UploadMetadata](./storage.uploadmetadata.md#uploadmetadata_interface) | Metadata for the string to upload. | - -Returns: - -Promise<[UploadResult](./storage.uploadresult.md#uploadresult_interface)> - -A Promise containing an UploadResult - -## StringFormat - -An enumeration of the possible string formats for upload. - -Signature: - -```typescript -StringFormat: { - readonly RAW: "raw"; - readonly BASE64: "base64"; - readonly BASE64URL: "base64url"; - readonly DATA_URL: "data_url"; -} -``` - -## StringFormat - -An enumeration of the possible string formats for upload. - -Signature: - -```typescript -export declare type StringFormat = typeof StringFormat[keyof typeof StringFormat]; -``` - -## TaskEvent - -An event that is triggered on a task. - -Signature: - -```typescript -export declare type TaskEvent = 'state_changed'; -``` - -## TaskState - -Represents the current state of a running upload. - -Signature: - -```typescript -export declare type TaskState = 'running' | 'paused' | 'success' | 'canceled' | 'error'; -``` diff --git a/docs-devsite/storage.settablemetadata.md b/docs-devsite/storage.settablemetadata.md deleted file mode 100644 index c721cc6c4f0..00000000000 --- a/docs-devsite/storage.settablemetadata.md +++ /dev/null @@ -1,92 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# SettableMetadata interface -Object metadata that can be set at any time. - -Signature: - -```typescript -export interface SettableMetadata -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [cacheControl](./storage.settablemetadata.md#settablemetadatacachecontrol) | string \| undefined | Served as the 'Cache-Control' header on object download. | -| [contentDisposition](./storage.settablemetadata.md#settablemetadatacontentdisposition) | string \| undefined | Served as the 'Content-Disposition' header on object download. | -| [contentEncoding](./storage.settablemetadata.md#settablemetadatacontentencoding) | string \| undefined | Served as the 'Content-Encoding' header on object download. | -| [contentLanguage](./storage.settablemetadata.md#settablemetadatacontentlanguage) | string \| undefined | Served as the 'Content-Language' header on object download. | -| [contentType](./storage.settablemetadata.md#settablemetadatacontenttype) | string \| undefined | Served as the 'Content-Type' header on object download. | -| [customMetadata](./storage.settablemetadata.md#settablemetadatacustommetadata) | { \[key: string\]: string; } \| undefined | Additional user-defined custom metadata. | - -## SettableMetadata.cacheControl - -Served as the 'Cache-Control' header on object download. - -Signature: - -```typescript -cacheControl?: string | undefined; -``` - -## SettableMetadata.contentDisposition - -Served as the 'Content-Disposition' header on object download. - -Signature: - -```typescript -contentDisposition?: string | undefined; -``` - -## SettableMetadata.contentEncoding - -Served as the 'Content-Encoding' header on object download. - -Signature: - -```typescript -contentEncoding?: string | undefined; -``` - -## SettableMetadata.contentLanguage - -Served as the 'Content-Language' header on object download. - -Signature: - -```typescript -contentLanguage?: string | undefined; -``` - -## SettableMetadata.contentType - -Served as the 'Content-Type' header on object download. - -Signature: - -```typescript -contentType?: string | undefined; -``` - -## SettableMetadata.customMetadata - -Additional user-defined custom metadata. - -Signature: - -```typescript -customMetadata?: { - [key: string]: string; - } | undefined; -``` diff --git a/docs-devsite/storage.storageerror.md b/docs-devsite/storage.storageerror.md deleted file mode 100644 index b204b37d785..00000000000 --- a/docs-devsite/storage.storageerror.md +++ /dev/null @@ -1,36 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# StorageError interface -An error returned by the Firebase Storage SDK. - -Signature: - -```typescript -export interface StorageError extends FirebaseError -``` -Extends: [FirebaseError](./util.firebaseerror.md#firebaseerror_class) - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [serverResponse](./storage.storageerror.md#storageerrorserverresponse) | string \| null | A server response message for the error, if applicable. | - -## StorageError.serverResponse - -A server response message for the error, if applicable. - -Signature: - -```typescript -serverResponse: string | null; -``` diff --git a/docs-devsite/storage.storageobserver.md b/docs-devsite/storage.storageobserver.md deleted file mode 100644 index 586b29c505f..00000000000 --- a/docs-devsite/storage.storageobserver.md +++ /dev/null @@ -1,51 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# StorageObserver interface -A stream observer for Firebase Storage. - -Signature: - -```typescript -export interface StorageObserver -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [complete](./storage.storageobserver.md#storageobservercomplete) | [CompleteFn](./util.md#completefn) \| null | | -| [error](./storage.storageobserver.md#storageobservererror) | (error: [StorageError](./storage.storageerror.md#storageerror_interface)) => void \| null | | -| [next](./storage.storageobserver.md#storageobservernext) | [NextFn](./util.md#nextfn)<T> \| null | | - -## StorageObserver.complete - -Signature: - -```typescript -complete?: CompleteFn | null; -``` - -## StorageObserver.error - -Signature: - -```typescript -error?: (error: StorageError) => void | null; -``` - -## StorageObserver.next - -Signature: - -```typescript -next?: NextFn | null; -``` diff --git a/docs-devsite/storage.storagereference.md b/docs-devsite/storage.storagereference.md deleted file mode 100644 index 4b584a428d5..00000000000 --- a/docs-devsite/storage.storagereference.md +++ /dev/null @@ -1,112 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# StorageReference interface -Represents a reference to a Google Cloud Storage object. Developers can upload, download, and delete objects, as well as get/set object metadata. - -Signature: - -```typescript -export interface StorageReference -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [bucket](./storage.storagereference.md#storagereferencebucket) | string | The name of the bucket containing this reference's object. | -| [fullPath](./storage.storagereference.md#storagereferencefullpath) | string | The full path of this object. | -| [name](./storage.storagereference.md#storagereferencename) | string | The short name of this object, which is the last component of the full path. For example, if fullPath is 'full/path/image.png', name is 'image.png'. | -| [parent](./storage.storagereference.md#storagereferenceparent) | [StorageReference](./storage.storagereference.md#storagereference_interface) \| null | A reference pointing to the parent location of this reference, or null if this reference is the root. | -| [root](./storage.storagereference.md#storagereferenceroot) | [StorageReference](./storage.storagereference.md#storagereference_interface) | A reference to the root of this object's bucket. | -| [storage](./storage.storagereference.md#storagereferencestorage) | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) | The [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance associated with this reference. | - -## Methods - -| Method | Description | -| --- | --- | -| [toString()](./storage.storagereference.md#storagereferencetostring) | Returns a gs:// URL for this object in the form gs://<bucket>/<path>/<to>/<object> | - -## StorageReference.bucket - -The name of the bucket containing this reference's object. - -Signature: - -```typescript -bucket: string; -``` - -## StorageReference.fullPath - -The full path of this object. - -Signature: - -```typescript -fullPath: string; -``` - -## StorageReference.name - -The short name of this object, which is the last component of the full path. For example, if fullPath is 'full/path/image.png', name is 'image.png'. - -Signature: - -```typescript -name: string; -``` - -## StorageReference.parent - -A reference pointing to the parent location of this reference, or null if this reference is the root. - -Signature: - -```typescript -parent: StorageReference | null; -``` - -## StorageReference.root - -A reference to the root of this object's bucket. - -Signature: - -```typescript -root: StorageReference; -``` - -## StorageReference.storage - -The [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance associated with this reference. - -Signature: - -```typescript -storage: FirebaseStorage; -``` - -## StorageReference.toString() - -Returns a gs:// URL for this object in the form `gs://///` - -Signature: - -```typescript -toString(): string; -``` -Returns: - -string - -The gs:// URL. - diff --git a/docs-devsite/storage.uploadmetadata.md b/docs-devsite/storage.uploadmetadata.md deleted file mode 100644 index 2b207401736..00000000000 --- a/docs-devsite/storage.uploadmetadata.md +++ /dev/null @@ -1,36 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# UploadMetadata interface -Object metadata that can be set at upload. - -Signature: - -```typescript -export interface UploadMetadata extends SettableMetadata -``` -Extends: [SettableMetadata](./storage.settablemetadata.md#settablemetadata_interface) - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [md5Hash](./storage.uploadmetadata.md#uploadmetadatamd5hash) | string \| undefined | A Base64-encoded MD5 hash of the object being uploaded. | - -## UploadMetadata.md5Hash - -A Base64-encoded MD5 hash of the object being uploaded. - -Signature: - -```typescript -md5Hash?: string | undefined; -``` diff --git a/docs-devsite/storage.uploadresult.md b/docs-devsite/storage.uploadresult.md deleted file mode 100644 index 05e3542ee62..00000000000 --- a/docs-devsite/storage.uploadresult.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# UploadResult interface -Result returned from a non-resumable upload. - -Signature: - -```typescript -export interface UploadResult -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [metadata](./storage.uploadresult.md#uploadresultmetadata) | [FullMetadata](./storage.fullmetadata.md#fullmetadata_interface) | Contains the metadata sent back from the server. | -| [ref](./storage.uploadresult.md#uploadresultref) | [StorageReference](./storage.storagereference.md#storagereference_interface) | The reference that spawned this upload. | - -## UploadResult.metadata - -Contains the metadata sent back from the server. - -Signature: - -```typescript -readonly metadata: FullMetadata; -``` - -## UploadResult.ref - -The reference that spawned this upload. - -Signature: - -```typescript -readonly ref: StorageReference; -``` diff --git a/docs-devsite/storage.uploadtask.md b/docs-devsite/storage.uploadtask.md deleted file mode 100644 index 095c54d95ff..00000000000 --- a/docs-devsite/storage.uploadtask.md +++ /dev/null @@ -1,255 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# UploadTask interface -Represents the process of uploading an object. Allows you to monitor and manage the upload. - -Signature: - -```typescript -export interface UploadTask -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [snapshot](./storage.uploadtask.md#uploadtasksnapshot) | [UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface) | A snapshot of the current task state. | - -## Methods - -| Method | Description | -| --- | --- | -| [cancel()](./storage.uploadtask.md#uploadtaskcancel) | Cancels a running task. Has no effect on a complete or failed task. | -| [catch(onRejected)](./storage.uploadtask.md#uploadtaskcatch) | Equivalent to calling then(null, onRejected). | -| [on(event, nextOrObserver, error, complete)](./storage.uploadtask.md#uploadtaskon) | Listens for events on this task.Events have three callback functions (referred to as next, error, and complete).If only the event is passed, a function that can be used to register the callbacks is returned. Otherwise, the callbacks are passed after the event.Callbacks can be passed either as three separate arguments or as the next, error, and complete properties of an object. Any of the three callbacks is optional, as long as at least one is specified. In addition, when you add your callbacks, you get a function back. You can call this function to unregister the associated callbacks. | -| [pause()](./storage.uploadtask.md#uploadtaskpause) | Pauses a currently running task. Has no effect on a paused or failed task. | -| [resume()](./storage.uploadtask.md#uploadtaskresume) | Resumes a paused task. Has no effect on a currently running or failed task. | -| [then(onFulfilled, onRejected)](./storage.uploadtask.md#uploadtaskthen) | This object behaves like a Promise, and resolves with its snapshot data when the upload completes. | - -## UploadTask.snapshot - -A snapshot of the current task state. - -Signature: - -```typescript -snapshot: UploadTaskSnapshot; -``` - -## UploadTask.cancel() - -Cancels a running task. Has no effect on a complete or failed task. - -Signature: - -```typescript -cancel(): boolean; -``` -Returns: - -boolean - -True if the cancel had an effect. - -## UploadTask.catch() - -Equivalent to calling `then(null, onRejected)`. - -Signature: - -```typescript -catch(onRejected: (error: StorageError) => unknown): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| onRejected | (error: [StorageError](./storage.storageerror.md#storageerror_interface)) => unknown | | - -Returns: - -Promise<unknown> - -## UploadTask.on() - -Listens for events on this task. - -Events have three callback functions (referred to as `next`, `error`, and `complete`). - -If only the event is passed, a function that can be used to register the callbacks is returned. Otherwise, the callbacks are passed after the event. - -Callbacks can be passed either as three separate arguments or as the `next`, `error`, and `complete` properties of an object. Any of the three callbacks is optional, as long as at least one is specified. In addition, when you add your callbacks, you get a function back. You can call this function to unregister the associated callbacks. - -Signature: - -```typescript -on(event: TaskEvent, nextOrObserver?: StorageObserver | null | ((snapshot: UploadTaskSnapshot) => unknown), error?: ((a: StorageError) => unknown) | null, complete?: Unsubscribe | null): Unsubscribe | Subscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| event | [TaskEvent](./storage.md#taskevent) | The type of event to listen for. | -| nextOrObserver | [StorageObserver](./storage.storageobserver.md#storageobserver_interface)<[UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface)> \| null \| ((snapshot: [UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface)) => unknown) | The next function, which gets called for each item in the event stream, or an observer object with some or all of these three properties (next, error, complete). | -| error | ((a: [StorageError](./storage.storageerror.md#storageerror_interface)) => unknown) \| null | A function that gets called with a StorageError if the event stream ends due to an error. | -| complete | [Unsubscribe](./util.md#unsubscribe) \| null | | - -Returns: - -[Unsubscribe](./util.md#unsubscribe) \| [Subscribe](./util.subscribe.md#subscribe_interface)<[UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface)> - -If only the event argument is passed, returns a function you can use to add callbacks (see the examples above). If more than just the event argument is passed, returns a function you can call to unregister the callbacks. - -### Example 1 - -\*\*Pass callbacks separately or in an object.\*\* - -```javascript -var next = function(snapshot) {}; -var error = function(error) {}; -var complete = function() {}; - -// The first example. -uploadTask.on( - firebase.storage.TaskEvent.STATE_CHANGED, - next, - error, - complete); - -// This is equivalent to the first example. -uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED, { - 'next': next, - 'error': error, - 'complete': complete -}); - -// This is equivalent to the first example. -var subscribe = uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED); -subscribe(next, error, complete); - -// This is equivalent to the first example. -var subscribe = uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED); -subscribe({ - 'next': next, - 'error': error, - 'complete': complete -}); - -``` - -### Example 2 - -\*\*Any callback is optional.\*\* - -```javascript -// Just listening for completion, this is legal. -uploadTask.on( - firebase.storage.TaskEvent.STATE_CHANGED, - null, - null, - function() { - console.log('upload complete!'); - }); - -// Just listening for progress/state changes, this is legal. -uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED, function(snapshot) { - var percent = snapshot.bytesTransferred / snapshot.totalBytes * 100; - console.log(percent + "% done"); -}); - -// This is also legal. -uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED, { - 'complete': function() { - console.log('upload complete!'); - } -}); - -``` - -### Example 3 - -\*\*Use the returned function to remove callbacks.\*\* - -```javascript -var unsubscribe = uploadTask.on( - firebase.storage.TaskEvent.STATE_CHANGED, - function(snapshot) { - var percent = snapshot.bytesTransferred / snapshot.totalBytes * 100; - console.log(percent + "% done"); - // Stop after receiving one update. - unsubscribe(); - }); - -// This code is equivalent to the above. -var handle = uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED); -unsubscribe = handle(function(snapshot) { - var percent = snapshot.bytesTransferred / snapshot.totalBytes * 100; - console.log(percent + "% done"); - // Stop after receiving one update. - unsubscribe(); -}); - -``` - -## UploadTask.pause() - -Pauses a currently running task. Has no effect on a paused or failed task. - -Signature: - -```typescript -pause(): boolean; -``` -Returns: - -boolean - -True if the operation took effect, false if ignored. - -## UploadTask.resume() - -Resumes a paused task. Has no effect on a currently running or failed task. - -Signature: - -```typescript -resume(): boolean; -``` -Returns: - -boolean - -True if the operation took effect, false if ignored. - -## UploadTask.then() - -This object behaves like a Promise, and resolves with its snapshot data when the upload completes. - -Signature: - -```typescript -then(onFulfilled?: ((snapshot: UploadTaskSnapshot) => unknown) | null, onRejected?: ((error: StorageError) => unknown) | null): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| onFulfilled | ((snapshot: [UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface)) => unknown) \| null | The fulfillment callback. Promise chaining works as normal. | -| onRejected | ((error: [StorageError](./storage.storageerror.md#storageerror_interface)) => unknown) \| null | The rejection callback. | - -Returns: - -Promise<unknown> - diff --git a/docs-devsite/storage.uploadtasksnapshot.md b/docs-devsite/storage.uploadtasksnapshot.md deleted file mode 100644 index 351ff7a2154..00000000000 --- a/docs-devsite/storage.uploadtasksnapshot.md +++ /dev/null @@ -1,90 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# UploadTaskSnapshot interface -Holds data about the current state of the upload task. - -Signature: - -```typescript -export interface UploadTaskSnapshot -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [bytesTransferred](./storage.uploadtasksnapshot.md#uploadtasksnapshotbytestransferred) | number | The number of bytes that have been successfully uploaded so far. | -| [metadata](./storage.uploadtasksnapshot.md#uploadtasksnapshotmetadata) | [FullMetadata](./storage.fullmetadata.md#fullmetadata_interface) | Before the upload completes, contains the metadata sent to the server. After the upload completes, contains the metadata sent back from the server. | -| [ref](./storage.uploadtasksnapshot.md#uploadtasksnapshotref) | [StorageReference](./storage.storagereference.md#storagereference_interface) | The reference that spawned this snapshot's upload task. | -| [state](./storage.uploadtasksnapshot.md#uploadtasksnapshotstate) | [TaskState](./storage.md#taskstate) | The current state of the task. | -| [task](./storage.uploadtasksnapshot.md#uploadtasksnapshottask) | [UploadTask](./storage.uploadtask.md#uploadtask_interface) | The task of which this is a snapshot. | -| [totalBytes](./storage.uploadtasksnapshot.md#uploadtasksnapshottotalbytes) | number | The total number of bytes to be uploaded. | - -## UploadTaskSnapshot.bytesTransferred - -The number of bytes that have been successfully uploaded so far. - -Signature: - -```typescript -bytesTransferred: number; -``` - -## UploadTaskSnapshot.metadata - -Before the upload completes, contains the metadata sent to the server. After the upload completes, contains the metadata sent back from the server. - -Signature: - -```typescript -metadata: FullMetadata; -``` - -## UploadTaskSnapshot.ref - -The reference that spawned this snapshot's upload task. - -Signature: - -```typescript -ref: StorageReference; -``` - -## UploadTaskSnapshot.state - -The current state of the task. - -Signature: - -```typescript -state: TaskState; -``` - -## UploadTaskSnapshot.task - -The task of which this is a snapshot. - -Signature: - -```typescript -task: UploadTask; -``` - -## UploadTaskSnapshot.totalBytes - -The total number of bytes to be uploaded. - -Signature: - -```typescript -totalBytes: number; -``` From 9d7a8d2d23a422e0f67d34d33a73981b32e45fbf Mon Sep 17 00:00:00 2001 From: Christina Holland Date: Mon, 6 Feb 2023 15:10:56 -0800 Subject: [PATCH 03/12] finish the job --- .github/CODEOWNERS | 2 +- .../firestore_.queryendatconstraint.md | 36 ------------------ .../firestore_.queryfieldfilterconstraint.md | 36 ------------------ .../firestore_.querylimitconstraint.md | 36 ------------------ .../firestore_.queryorderbyconstraint.md | 38 ------------------- .../firestore_.querystartatconstraint.md | 36 ------------------ .../firestore_lite.queryendatconstraint.md | 36 ------------------ ...restore_lite.queryfieldfilterconstraint.md | 36 ------------------ .../firestore_lite.querylimitconstraint.md | 36 ------------------ .../firestore_lite.queryorderbyconstraint.md | 38 ------------------- .../firestore_lite.querystartatconstraint.md | 36 ------------------ 11 files changed, 1 insertion(+), 365 deletions(-) delete mode 100644 docs-devsite/firestore_.queryendatconstraint.md delete mode 100644 docs-devsite/firestore_.queryfieldfilterconstraint.md delete mode 100644 docs-devsite/firestore_.querylimitconstraint.md delete mode 100644 docs-devsite/firestore_.queryorderbyconstraint.md delete mode 100644 docs-devsite/firestore_.querystartatconstraint.md delete mode 100644 docs-devsite/firestore_lite.queryendatconstraint.md delete mode 100644 docs-devsite/firestore_lite.queryfieldfilterconstraint.md delete mode 100644 docs-devsite/firestore_lite.querylimitconstraint.md delete mode 100644 docs-devsite/firestore_lite.queryorderbyconstraint.md delete mode 100644 docs-devsite/firestore_lite.querystartatconstraint.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 7fc0473cbfa..b6f99258182 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -96,7 +96,7 @@ packages/app-check-interop-types @hsubox76 @firebase/jssdk-global-approvers # Documentation Changes packages/firebase/index.d.ts @egilmorez @firebase/jssdk-global-approvers scripts/docgen/content-sources/ @egilmorez @firebase/jssdk-global-approvers -docs-devsite/ +docs-devsite/ # Changeset .changeset @egilmorez @firebase/jssdk-changeset-approvers @firebase/firestore-js-team @firebase/jssdk-global-approvers \ No newline at end of file diff --git a/docs-devsite/firestore_.queryendatconstraint.md b/docs-devsite/firestore_.queryendatconstraint.md deleted file mode 100644 index 44dcddab71b..00000000000 --- a/docs-devsite/firestore_.queryendatconstraint.md +++ /dev/null @@ -1,36 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryEndAtConstraint class -A `QueryEndAtConstraint` is used to exclude documents from the end of a result set returned by a Firestore query. `QueryEndAtConstraint`s are created by invoking [endAt()](./firestore_.md#endat) or [endBefore()](./firestore_.md#endbefore) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryEndAtConstraint`. - -Signature: - -```typescript -export declare class QueryEndAtConstraint extends QueryConstraint -``` -Extends: [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_.queryendatconstraint.md#queryendatconstrainttype) | | 'endBefore' \| 'endAt' | The type of this query constraint | - -## QueryEndAtConstraint.type - -The type of this query constraint - -Signature: - -```typescript -readonly type: 'endBefore' | 'endAt'; -``` diff --git a/docs-devsite/firestore_.queryfieldfilterconstraint.md b/docs-devsite/firestore_.queryfieldfilterconstraint.md deleted file mode 100644 index 18710b6aa99..00000000000 --- a/docs-devsite/firestore_.queryfieldfilterconstraint.md +++ /dev/null @@ -1,36 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryFieldFilterConstraint class -A `QueryFieldFilterConstraint` is used to narrow the set of documents returned by a Firestore query by filtering on one or more document fields. `QueryFieldFilterConstraint`s are created by invoking [where()](./firestore_.md#where) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryFieldFilterConstraint`. - -Signature: - -```typescript -export declare class QueryFieldFilterConstraint extends QueryConstraint -``` -Extends: [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstrainttype) | | (not declared) | The type of this query constraint | - -## QueryFieldFilterConstraint.type - -The type of this query constraint - -Signature: - -```typescript -readonly type = "where"; -``` diff --git a/docs-devsite/firestore_.querylimitconstraint.md b/docs-devsite/firestore_.querylimitconstraint.md deleted file mode 100644 index 72b06d61073..00000000000 --- a/docs-devsite/firestore_.querylimitconstraint.md +++ /dev/null @@ -1,36 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryLimitConstraint class -A `QueryLimitConstraint` is used to limit the number of documents returned by a Firestore query. `QueryLimitConstraint`s are created by invoking [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryLimitConstraint`. - -Signature: - -```typescript -export declare class QueryLimitConstraint extends QueryConstraint -``` -Extends: [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_.querylimitconstraint.md#querylimitconstrainttype) | | 'limit' \| 'limitToLast' | The type of this query constraint | - -## QueryLimitConstraint.type - -The type of this query constraint - -Signature: - -```typescript -readonly type: 'limit' | 'limitToLast'; -``` diff --git a/docs-devsite/firestore_.queryorderbyconstraint.md b/docs-devsite/firestore_.queryorderbyconstraint.md deleted file mode 100644 index 6f24ac985dd..00000000000 --- a/docs-devsite/firestore_.queryorderbyconstraint.md +++ /dev/null @@ -1,38 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryOrderByConstraint class -A `QueryOrderByConstraint` is used to sort the set of documents returned by a Firestore query. `QueryOrderByConstraint`s are created by invoking [orderBy()](./firestore_.md#orderby) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryOrderByConstraint`. - -Note: Documents that do not contain the orderBy field will not be present in the query result. - -Signature: - -```typescript -export declare class QueryOrderByConstraint extends QueryConstraint -``` -Extends: [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_.queryorderbyconstraint.md#queryorderbyconstrainttype) | | (not declared) | The type of this query constraint | - -## QueryOrderByConstraint.type - -The type of this query constraint - -Signature: - -```typescript -readonly type = "orderBy"; -``` diff --git a/docs-devsite/firestore_.querystartatconstraint.md b/docs-devsite/firestore_.querystartatconstraint.md deleted file mode 100644 index edad47f66ee..00000000000 --- a/docs-devsite/firestore_.querystartatconstraint.md +++ /dev/null @@ -1,36 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryStartAtConstraint class -A `QueryStartAtConstraint` is used to exclude documents from the start of a result set returned by a Firestore query. `QueryStartAtConstraint`s are created by invoking [startAt()](./firestore_.md#startat) or [startAfter()](./firestore_.md#startafter) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryStartAtConstraint`. - -Signature: - -```typescript -export declare class QueryStartAtConstraint extends QueryConstraint -``` -Extends: [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_.querystartatconstraint.md#querystartatconstrainttype) | | 'startAt' \| 'startAfter' | The type of this query constraint | - -## QueryStartAtConstraint.type - -The type of this query constraint - -Signature: - -```typescript -readonly type: 'startAt' | 'startAfter'; -``` diff --git a/docs-devsite/firestore_lite.queryendatconstraint.md b/docs-devsite/firestore_lite.queryendatconstraint.md deleted file mode 100644 index 7f999a414b6..00000000000 --- a/docs-devsite/firestore_lite.queryendatconstraint.md +++ /dev/null @@ -1,36 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryEndAtConstraint class -A `QueryEndAtConstraint` is used to exclude documents from the end of a result set returned by a Firestore query. `QueryEndAtConstraint`s are created by invoking [endAt()](./firestore_.md#endat) or [endBefore()](./firestore_.md#endbefore) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryEndAtConstraint`. - -Signature: - -```typescript -export declare class QueryEndAtConstraint extends QueryConstraint -``` -Extends: [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_lite.queryendatconstraint.md#queryendatconstrainttype) | | 'endBefore' \| 'endAt' | The type of this query constraint | - -## QueryEndAtConstraint.type - -The type of this query constraint - -Signature: - -```typescript -readonly type: 'endBefore' | 'endAt'; -``` diff --git a/docs-devsite/firestore_lite.queryfieldfilterconstraint.md b/docs-devsite/firestore_lite.queryfieldfilterconstraint.md deleted file mode 100644 index 81c1509223d..00000000000 --- a/docs-devsite/firestore_lite.queryfieldfilterconstraint.md +++ /dev/null @@ -1,36 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryFieldFilterConstraint class -A `QueryFieldFilterConstraint` is used to narrow the set of documents returned by a Firestore query by filtering on one or more document fields. `QueryFieldFilterConstraint`s are created by invoking [where()](./firestore_.md#where) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryFieldFilterConstraint`. - -Signature: - -```typescript -export declare class QueryFieldFilterConstraint extends QueryConstraint -``` -Extends: [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_lite.queryfieldfilterconstraint.md#queryfieldfilterconstrainttype) | | (not declared) | The type of this query constraint | - -## QueryFieldFilterConstraint.type - -The type of this query constraint - -Signature: - -```typescript -readonly type = "where"; -``` diff --git a/docs-devsite/firestore_lite.querylimitconstraint.md b/docs-devsite/firestore_lite.querylimitconstraint.md deleted file mode 100644 index 82218279e34..00000000000 --- a/docs-devsite/firestore_lite.querylimitconstraint.md +++ /dev/null @@ -1,36 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryLimitConstraint class -A `QueryLimitConstraint` is used to limit the number of documents returned by a Firestore query. `QueryLimitConstraint`s are created by invoking [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryLimitConstraint`. - -Signature: - -```typescript -export declare class QueryLimitConstraint extends QueryConstraint -``` -Extends: [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_lite.querylimitconstraint.md#querylimitconstrainttype) | | 'limit' \| 'limitToLast' | The type of this query constraint | - -## QueryLimitConstraint.type - -The type of this query constraint - -Signature: - -```typescript -readonly type: 'limit' | 'limitToLast'; -``` diff --git a/docs-devsite/firestore_lite.queryorderbyconstraint.md b/docs-devsite/firestore_lite.queryorderbyconstraint.md deleted file mode 100644 index b5a28ed3e9a..00000000000 --- a/docs-devsite/firestore_lite.queryorderbyconstraint.md +++ /dev/null @@ -1,38 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryOrderByConstraint class -A `QueryOrderByConstraint` is used to sort the set of documents returned by a Firestore query. `QueryOrderByConstraint`s are created by invoking [orderBy()](./firestore_.md#orderby) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryOrderByConstraint`. - -Note: Documents that do not contain the orderBy field will not be present in the query result. - -Signature: - -```typescript -export declare class QueryOrderByConstraint extends QueryConstraint -``` -Extends: [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_lite.queryorderbyconstraint.md#queryorderbyconstrainttype) | | (not declared) | The type of this query constraint | - -## QueryOrderByConstraint.type - -The type of this query constraint - -Signature: - -```typescript -readonly type = "orderBy"; -``` diff --git a/docs-devsite/firestore_lite.querystartatconstraint.md b/docs-devsite/firestore_lite.querystartatconstraint.md deleted file mode 100644 index 08d6ba15103..00000000000 --- a/docs-devsite/firestore_lite.querystartatconstraint.md +++ /dev/null @@ -1,36 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryStartAtConstraint class -A `QueryStartAtConstraint` is used to exclude documents from the start of a result set returned by a Firestore query. `QueryStartAtConstraint`s are created by invoking [startAt()](./firestore_.md#startat) or [startAfter()](./firestore_.md#startafter) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryStartAtConstraint`. - -Signature: - -```typescript -export declare class QueryStartAtConstraint extends QueryConstraint -``` -Extends: [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_lite.querystartatconstraint.md#querystartatconstrainttype) | | 'startAt' \| 'startAfter' | The type of this query constraint | - -## QueryStartAtConstraint.type - -The type of this query constraint - -Signature: - -```typescript -readonly type: 'startAt' | 'startAfter'; -``` From 7ed66ee92d19d8d3da26e66e1ee5675066c213a7 Mon Sep 17 00:00:00 2001 From: Christina Holland Date: Mon, 6 Feb 2023 15:14:00 -0800 Subject: [PATCH 04/12] Fix up workflow --- .github/CODEOWNERS | 2 +- .github/workflows/check-docs.yml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index b6f99258182..0c5b9da0f5e 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -96,7 +96,7 @@ packages/app-check-interop-types @hsubox76 @firebase/jssdk-global-approvers # Documentation Changes packages/firebase/index.d.ts @egilmorez @firebase/jssdk-global-approvers scripts/docgen/content-sources/ @egilmorez @firebase/jssdk-global-approvers -docs-devsite/ +docs-devsite/ @egilmorez @markarndt # Changeset .changeset @egilmorez @firebase/jssdk-changeset-approvers @firebase/firestore-js-team @firebase/jssdk-global-approvers \ No newline at end of file diff --git a/.github/workflows/check-docs.yml b/.github/workflows/check-docs.yml index f6ea11c6faf..4e97150b2b5 100644 --- a/.github/workflows/check-docs.yml +++ b/.github/workflows/check-docs.yml @@ -1,4 +1,4 @@ -name: Doc Change Check (Run yarn format locally if this fails) +name: Doc Change Check (Run "yarn docgen devsite" if this fails) on: pull_request @@ -27,4 +27,4 @@ jobs: git diff --exit-code - name: Reference documentation needs to be updated. See message below. if: ${{ failure() }} - run: echo "Changes in this PR affect the reference docs. Run \`yarn docgen\` locally to regenerate docs and add them to this PR." \ No newline at end of file + run: echo "Changes in this PR affect the reference docs. Run \`yarn docgen devsite\` locally to regenerate docs and add them to this PR." \ No newline at end of file From 26da6ad4a092d38f92f70df3f8bde7fa3c6ad738 Mon Sep 17 00:00:00 2001 From: Christina Holland Date: Mon, 13 Feb 2023 09:48:47 -0800 Subject: [PATCH 05/12] trigger CI From 432218dc4a69ae0bcedd209ca16c255955c056be Mon Sep 17 00:00:00 2001 From: Christina Holland Date: Mon, 13 Feb 2023 12:28:49 -0800 Subject: [PATCH 06/12] get docs, update docgen script --- .github/CODEOWNERS | 2 +- common/api-review/auth.api.md | 27 +- docs-devsite/analytics.analytics.md | 35 + .../analytics.analyticscalloptions.md | 35 + docs-devsite/analytics.analyticssettings.md | 35 + docs-devsite/analytics.consentsettings.md | 79 + docs-devsite/analytics.controlparams.md | 60 + docs-devsite/analytics.customparams.md | 19 + docs-devsite/analytics.eventparams.md | 316 +++ docs-devsite/analytics.gtagconfigparams.md | 134 ++ docs-devsite/analytics.item.md | 278 +++ docs-devsite/analytics.md | 991 ++++++++ docs-devsite/analytics.promotion.md | 65 + docs-devsite/analytics.settingsoptions.md | 46 + docs-devsite/app-check.appcheck.md | 35 + docs-devsite/app-check.appcheckoptions.md | 46 + docs-devsite/app-check.appchecktoken.md | 44 + docs-devsite/app-check.appchecktokenresult.md | 35 + docs-devsite/app-check.customprovider.md | 43 + .../app-check.customprovideroptions.md | 35 + docs-devsite/app-check.md | 170 ++ .../app-check.recaptchaenterpriseprovider.md | 43 + docs-devsite/app-check.recaptchav3provider.md | 43 + docs-devsite/app.firebaseapp.md | 91 + docs-devsite/app.firebaseappsettings.md | 46 + docs-devsite/app.firebaseoptions.md | 112 + docs-devsite/app.md | 306 +++ docs-devsite/auth.actioncodeinfo.md | 58 + docs-devsite/auth.actioncodesettings.md | 95 + docs-devsite/auth.actioncodeurl.md | 121 + docs-devsite/auth.additionaluserinfo.md | 68 + docs-devsite/auth.applicationverifier.md | 59 + docs-devsite/auth.auth.md | 299 +++ docs-devsite/auth.authcredential.md | 76 + docs-devsite/auth.autherror.md | 41 + docs-devsite/auth.autherrormap.md | 27 + docs-devsite/auth.authprovider.md | 35 + docs-devsite/auth.authsettings.md | 41 + docs-devsite/auth.config.md | 90 + docs-devsite/auth.confirmationresult.md | 74 + docs-devsite/auth.dependencies.md | 63 + docs-devsite/auth.emailauthcredential.md | 69 + docs-devsite/auth.emailauthprovider.md | 159 ++ docs-devsite/auth.emulatorconfig.md | 70 + docs-devsite/auth.facebookauthprovider.md | 182 ++ docs-devsite/auth.githubauthprovider.md | 174 ++ docs-devsite/auth.googleauthprovider.md | 185 ++ docs-devsite/auth.idtokenresult.md | 109 + docs-devsite/auth.md | 1992 +++++++++++++++ docs-devsite/auth.multifactorassertion.md | 37 + docs-devsite/auth.multifactorerror.md | 67 + docs-devsite/auth.multifactorinfo.md | 68 + docs-devsite/auth.multifactorresolver.md | 128 + docs-devsite/auth.multifactorsession.md | 19 + docs-devsite/auth.multifactoruser.md | 161 ++ docs-devsite/auth.oauthcredential.md | 105 + docs-devsite/auth.oauthcredentialoptions.md | 61 + docs-devsite/auth.oauthprovider.md | 168 ++ docs-devsite/auth.parsedtoken.md | 83 + docs-devsite/auth.persistence.md | 35 + docs-devsite/auth.phoneauthcredential.md | 63 + docs-devsite/auth.phoneauthprovider.md | 256 ++ .../auth.phonemultifactorassertion.md | 21 + .../auth.phonemultifactorenrollinfooptions.md | 46 + .../auth.phonemultifactorgenerator.md | 64 + docs-devsite/auth.phonemultifactorinfo.md | 36 + .../auth.phonemultifactorsignininfooptions.md | 61 + .../auth.phonesinglefactorinfooptions.md | 35 + docs-devsite/auth.popupredirectresolver.md | 19 + docs-devsite/auth.reactnativeasyncstorage.md | 89 + docs-devsite/auth.recaptchaparameters.md | 23 + docs-devsite/auth.recaptchaverifier.md | 116 + docs-devsite/auth.samlauthprovider.md | 119 + docs-devsite/auth.twitterauthprovider.md | 173 ++ docs-devsite/auth.user.md | 204 ++ docs-devsite/auth.usercredential.md | 59 + docs-devsite/auth.userinfo.md | 92 + docs-devsite/auth.usermetadata.md | 46 + docs-devsite/database.database.md | 46 + docs-devsite/database.databasereference.md | 68 + docs-devsite/database.datasnapshot.md | 237 ++ docs-devsite/database.listenoptions.md | 35 + docs-devsite/database.md | 1405 +++++++++++ docs-devsite/database.ondisconnect.md | 143 ++ docs-devsite/database.query.md | 108 + docs-devsite/database.queryconstraint.md | 35 + docs-devsite/database.thenablereference.md | 21 + docs-devsite/database.transactionoptions.md | 35 + docs-devsite/database.transactionresult.md | 66 + docs-devsite/firestore.md | 19 + docs-devsite/firestore_.aggregatefield.md | 35 + .../firestore_.aggregatequerysnapshot.md | 70 + docs-devsite/firestore_.aggregatespec.md | 19 + docs-devsite/firestore_.bytes.md | 138 ++ .../firestore_.collectionreference.md | 121 + docs-devsite/firestore_.documentchange.md | 68 + docs-devsite/firestore_.documentdata.md | 19 + docs-devsite/firestore_.documentreference.md | 142 ++ docs-devsite/firestore_.documentsnapshot.md | 146 ++ docs-devsite/firestore_.fieldpath.md | 72 + docs-devsite/firestore_.fieldvalue.md | 46 + docs-devsite/firestore_.firestore.md | 68 + .../firestore_.firestoredataconverter.md | 134 ++ docs-devsite/firestore_.firestoreerror.md | 58 + docs-devsite/firestore_.firestoresettings.md | 96 + docs-devsite/firestore_.geopoint.md | 117 + docs-devsite/firestore_.index.md | 55 + docs-devsite/firestore_.indexconfiguration.md | 43 + docs-devsite/firestore_.indexfield.md | 73 + docs-devsite/firestore_.loadbundletask.md | 94 + .../firestore_.loadbundletaskprogress.md | 79 + docs-devsite/firestore_.md | 2134 +++++++++++++++++ .../firestore_.persistencesettings.md | 35 + docs-devsite/firestore_.query.md | 125 + docs-devsite/firestore_.queryconstraint.md | 35 + .../firestore_.querydocumentsnapshot.md | 54 + .../firestore_.queryendatconstraint.md | 36 + .../firestore_.queryfieldfilterconstraint.md | 36 + .../firestore_.querylimitconstraint.md | 36 + .../firestore_.queryorderbyconstraint.md | 38 + docs-devsite/firestore_.querysnapshot.md | 128 + .../firestore_.querystartatconstraint.md | 36 + .../firestore_.snapshotlistenoptions.md | 35 + docs-devsite/firestore_.snapshotmetadata.md | 75 + docs-devsite/firestore_.snapshotoptions.md | 41 + docs-devsite/firestore_.timestamp.md | 243 ++ docs-devsite/firestore_.transaction.md | 190 ++ docs-devsite/firestore_.transactionoptions.md | 35 + docs-devsite/firestore_.unsubscribe.md | 19 + docs-devsite/firestore_.writebatch.md | 181 ++ docs-devsite/firestore_lite.aggregatefield.md | 35 + .../firestore_lite.aggregatequerysnapshot.md | 70 + docs-devsite/firestore_lite.aggregatespec.md | 19 + docs-devsite/firestore_lite.bytes.md | 138 ++ .../firestore_lite.collectionreference.md | 121 + docs-devsite/firestore_lite.documentdata.md | 19 + .../firestore_lite.documentreference.md | 142 ++ .../firestore_lite.documentsnapshot.md | 125 + docs-devsite/firestore_lite.fieldpath.md | 72 + docs-devsite/firestore_lite.fieldvalue.md | 46 + docs-devsite/firestore_lite.firestore.md | 68 + .../firestore_lite.firestoredataconverter.md | 130 + docs-devsite/firestore_lite.firestoreerror.md | 58 + docs-devsite/firestore_lite.geopoint.md | 117 + docs-devsite/firestore_lite.md | 1443 +++++++++++ docs-devsite/firestore_lite.query.md | 125 + .../firestore_lite.queryconstraint.md | 35 + .../firestore_lite.querydocumentsnapshot.md | 45 + .../firestore_lite.queryendatconstraint.md | 36 + ...restore_lite.queryfieldfilterconstraint.md | 36 + .../firestore_lite.querylimitconstraint.md | 36 + .../firestore_lite.queryorderbyconstraint.md | 38 + docs-devsite/firestore_lite.querysnapshot.md | 96 + .../firestore_lite.querystartatconstraint.md | 36 + docs-devsite/firestore_lite.settings.md | 57 + docs-devsite/firestore_lite.timestamp.md | 243 ++ docs-devsite/firestore_lite.transaction.md | 190 ++ .../firestore_lite.transactionoptions.md | 35 + docs-devsite/firestore_lite.writebatch.md | 181 ++ docs-devsite/functions.functions.md | 57 + docs-devsite/functions.functionserror.md | 47 + .../functions.httpscallableoptions.md | 35 + docs-devsite/functions.httpscallableresult.md | 35 + docs-devsite/functions.md | 162 ++ docs-devsite/index.md | 30 + docs-devsite/installations.installations.md | 35 + docs-devsite/installations.md | 162 ++ docs-devsite/messaging.md | 19 + docs-devsite/messaging_.fcmoptions.md | 46 + docs-devsite/messaging_.gettokenoptions.md | 46 + docs-devsite/messaging_.md | 143 ++ docs-devsite/messaging_.messagepayload.md | 92 + docs-devsite/messaging_.messaging.md | 35 + .../messaging_.notificationpayload.md | 68 + docs-devsite/messaging_sw.fcmoptions.md | 46 + docs-devsite/messaging_sw.gettokenoptions.md | 46 + docs-devsite/messaging_sw.md | 116 + docs-devsite/messaging_sw.messagepayload.md | 92 + docs-devsite/messaging_sw.messaging.md | 35 + .../messaging_sw.notificationpayload.md | 68 + .../performance.firebaseperformance.md | 57 + docs-devsite/performance.md | 94 + .../performance.performancesettings.md | 46 + docs-devsite/performance.performancetrace.md | 228 ++ docs-devsite/remote-config.md | 345 +++ docs-devsite/remote-config.remoteconfig.md | 81 + .../remote-config.remoteconfigsettings.md | 46 + docs-devsite/remote-config.value.md | 83 + docs-devsite/storage.firebasestorage.md | 58 + docs-devsite/storage.fullmetadata.md | 135 ++ docs-devsite/storage.listoptions.md | 46 + docs-devsite/storage.listresult.md | 59 + docs-devsite/storage.md | 550 +++++ docs-devsite/storage.settablemetadata.md | 92 + docs-devsite/storage.storageerror.md | 113 + docs-devsite/storage.storageobserver.md | 51 + docs-devsite/storage.storagereference.md | 112 + docs-devsite/storage.uploadmetadata.md | 36 + docs-devsite/storage.uploadresult.md | 46 + docs-devsite/storage.uploadtask.md | 255 ++ docs-devsite/storage.uploadtasksnapshot.md | 90 + packages/auth/api-extractor.json | 2 +- scripts/docgen/docgen.ts | 17 +- 203 files changed, 24969 insertions(+), 15 deletions(-) create mode 100644 docs-devsite/analytics.analytics.md create mode 100644 docs-devsite/analytics.analyticscalloptions.md create mode 100644 docs-devsite/analytics.analyticssettings.md create mode 100644 docs-devsite/analytics.consentsettings.md create mode 100644 docs-devsite/analytics.controlparams.md create mode 100644 docs-devsite/analytics.customparams.md create mode 100644 docs-devsite/analytics.eventparams.md create mode 100644 docs-devsite/analytics.gtagconfigparams.md create mode 100644 docs-devsite/analytics.item.md create mode 100644 docs-devsite/analytics.md create mode 100644 docs-devsite/analytics.promotion.md create mode 100644 docs-devsite/analytics.settingsoptions.md create mode 100644 docs-devsite/app-check.appcheck.md create mode 100644 docs-devsite/app-check.appcheckoptions.md create mode 100644 docs-devsite/app-check.appchecktoken.md create mode 100644 docs-devsite/app-check.appchecktokenresult.md create mode 100644 docs-devsite/app-check.customprovider.md create mode 100644 docs-devsite/app-check.customprovideroptions.md create mode 100644 docs-devsite/app-check.md create mode 100644 docs-devsite/app-check.recaptchaenterpriseprovider.md create mode 100644 docs-devsite/app-check.recaptchav3provider.md create mode 100644 docs-devsite/app.firebaseapp.md create mode 100644 docs-devsite/app.firebaseappsettings.md create mode 100644 docs-devsite/app.firebaseoptions.md create mode 100644 docs-devsite/app.md create mode 100644 docs-devsite/auth.actioncodeinfo.md create mode 100644 docs-devsite/auth.actioncodesettings.md create mode 100644 docs-devsite/auth.actioncodeurl.md create mode 100644 docs-devsite/auth.additionaluserinfo.md create mode 100644 docs-devsite/auth.applicationverifier.md create mode 100644 docs-devsite/auth.auth.md create mode 100644 docs-devsite/auth.authcredential.md create mode 100644 docs-devsite/auth.autherror.md create mode 100644 docs-devsite/auth.autherrormap.md create mode 100644 docs-devsite/auth.authprovider.md create mode 100644 docs-devsite/auth.authsettings.md create mode 100644 docs-devsite/auth.config.md create mode 100644 docs-devsite/auth.confirmationresult.md create mode 100644 docs-devsite/auth.dependencies.md create mode 100644 docs-devsite/auth.emailauthcredential.md create mode 100644 docs-devsite/auth.emailauthprovider.md create mode 100644 docs-devsite/auth.emulatorconfig.md create mode 100644 docs-devsite/auth.facebookauthprovider.md create mode 100644 docs-devsite/auth.githubauthprovider.md create mode 100644 docs-devsite/auth.googleauthprovider.md create mode 100644 docs-devsite/auth.idtokenresult.md create mode 100644 docs-devsite/auth.md create mode 100644 docs-devsite/auth.multifactorassertion.md create mode 100644 docs-devsite/auth.multifactorerror.md create mode 100644 docs-devsite/auth.multifactorinfo.md create mode 100644 docs-devsite/auth.multifactorresolver.md create mode 100644 docs-devsite/auth.multifactorsession.md create mode 100644 docs-devsite/auth.multifactoruser.md create mode 100644 docs-devsite/auth.oauthcredential.md create mode 100644 docs-devsite/auth.oauthcredentialoptions.md create mode 100644 docs-devsite/auth.oauthprovider.md create mode 100644 docs-devsite/auth.parsedtoken.md create mode 100644 docs-devsite/auth.persistence.md create mode 100644 docs-devsite/auth.phoneauthcredential.md create mode 100644 docs-devsite/auth.phoneauthprovider.md create mode 100644 docs-devsite/auth.phonemultifactorassertion.md create mode 100644 docs-devsite/auth.phonemultifactorenrollinfooptions.md create mode 100644 docs-devsite/auth.phonemultifactorgenerator.md create mode 100644 docs-devsite/auth.phonemultifactorinfo.md create mode 100644 docs-devsite/auth.phonemultifactorsignininfooptions.md create mode 100644 docs-devsite/auth.phonesinglefactorinfooptions.md create mode 100644 docs-devsite/auth.popupredirectresolver.md create mode 100644 docs-devsite/auth.reactnativeasyncstorage.md create mode 100644 docs-devsite/auth.recaptchaparameters.md create mode 100644 docs-devsite/auth.recaptchaverifier.md create mode 100644 docs-devsite/auth.samlauthprovider.md create mode 100644 docs-devsite/auth.twitterauthprovider.md create mode 100644 docs-devsite/auth.user.md create mode 100644 docs-devsite/auth.usercredential.md create mode 100644 docs-devsite/auth.userinfo.md create mode 100644 docs-devsite/auth.usermetadata.md create mode 100644 docs-devsite/database.database.md create mode 100644 docs-devsite/database.databasereference.md create mode 100644 docs-devsite/database.datasnapshot.md create mode 100644 docs-devsite/database.listenoptions.md create mode 100644 docs-devsite/database.md create mode 100644 docs-devsite/database.ondisconnect.md create mode 100644 docs-devsite/database.query.md create mode 100644 docs-devsite/database.queryconstraint.md create mode 100644 docs-devsite/database.thenablereference.md create mode 100644 docs-devsite/database.transactionoptions.md create mode 100644 docs-devsite/database.transactionresult.md create mode 100644 docs-devsite/firestore.md create mode 100644 docs-devsite/firestore_.aggregatefield.md create mode 100644 docs-devsite/firestore_.aggregatequerysnapshot.md create mode 100644 docs-devsite/firestore_.aggregatespec.md create mode 100644 docs-devsite/firestore_.bytes.md create mode 100644 docs-devsite/firestore_.collectionreference.md create mode 100644 docs-devsite/firestore_.documentchange.md create mode 100644 docs-devsite/firestore_.documentdata.md create mode 100644 docs-devsite/firestore_.documentreference.md create mode 100644 docs-devsite/firestore_.documentsnapshot.md create mode 100644 docs-devsite/firestore_.fieldpath.md create mode 100644 docs-devsite/firestore_.fieldvalue.md create mode 100644 docs-devsite/firestore_.firestore.md create mode 100644 docs-devsite/firestore_.firestoredataconverter.md create mode 100644 docs-devsite/firestore_.firestoreerror.md create mode 100644 docs-devsite/firestore_.firestoresettings.md create mode 100644 docs-devsite/firestore_.geopoint.md create mode 100644 docs-devsite/firestore_.index.md create mode 100644 docs-devsite/firestore_.indexconfiguration.md create mode 100644 docs-devsite/firestore_.indexfield.md create mode 100644 docs-devsite/firestore_.loadbundletask.md create mode 100644 docs-devsite/firestore_.loadbundletaskprogress.md create mode 100644 docs-devsite/firestore_.md create mode 100644 docs-devsite/firestore_.persistencesettings.md create mode 100644 docs-devsite/firestore_.query.md create mode 100644 docs-devsite/firestore_.queryconstraint.md create mode 100644 docs-devsite/firestore_.querydocumentsnapshot.md create mode 100644 docs-devsite/firestore_.queryendatconstraint.md create mode 100644 docs-devsite/firestore_.queryfieldfilterconstraint.md create mode 100644 docs-devsite/firestore_.querylimitconstraint.md create mode 100644 docs-devsite/firestore_.queryorderbyconstraint.md create mode 100644 docs-devsite/firestore_.querysnapshot.md create mode 100644 docs-devsite/firestore_.querystartatconstraint.md create mode 100644 docs-devsite/firestore_.snapshotlistenoptions.md create mode 100644 docs-devsite/firestore_.snapshotmetadata.md create mode 100644 docs-devsite/firestore_.snapshotoptions.md create mode 100644 docs-devsite/firestore_.timestamp.md create mode 100644 docs-devsite/firestore_.transaction.md create mode 100644 docs-devsite/firestore_.transactionoptions.md create mode 100644 docs-devsite/firestore_.unsubscribe.md create mode 100644 docs-devsite/firestore_.writebatch.md create mode 100644 docs-devsite/firestore_lite.aggregatefield.md create mode 100644 docs-devsite/firestore_lite.aggregatequerysnapshot.md create mode 100644 docs-devsite/firestore_lite.aggregatespec.md create mode 100644 docs-devsite/firestore_lite.bytes.md create mode 100644 docs-devsite/firestore_lite.collectionreference.md create mode 100644 docs-devsite/firestore_lite.documentdata.md create mode 100644 docs-devsite/firestore_lite.documentreference.md create mode 100644 docs-devsite/firestore_lite.documentsnapshot.md create mode 100644 docs-devsite/firestore_lite.fieldpath.md create mode 100644 docs-devsite/firestore_lite.fieldvalue.md create mode 100644 docs-devsite/firestore_lite.firestore.md create mode 100644 docs-devsite/firestore_lite.firestoredataconverter.md create mode 100644 docs-devsite/firestore_lite.firestoreerror.md create mode 100644 docs-devsite/firestore_lite.geopoint.md create mode 100644 docs-devsite/firestore_lite.md create mode 100644 docs-devsite/firestore_lite.query.md create mode 100644 docs-devsite/firestore_lite.queryconstraint.md create mode 100644 docs-devsite/firestore_lite.querydocumentsnapshot.md create mode 100644 docs-devsite/firestore_lite.queryendatconstraint.md create mode 100644 docs-devsite/firestore_lite.queryfieldfilterconstraint.md create mode 100644 docs-devsite/firestore_lite.querylimitconstraint.md create mode 100644 docs-devsite/firestore_lite.queryorderbyconstraint.md create mode 100644 docs-devsite/firestore_lite.querysnapshot.md create mode 100644 docs-devsite/firestore_lite.querystartatconstraint.md create mode 100644 docs-devsite/firestore_lite.settings.md create mode 100644 docs-devsite/firestore_lite.timestamp.md create mode 100644 docs-devsite/firestore_lite.transaction.md create mode 100644 docs-devsite/firestore_lite.transactionoptions.md create mode 100644 docs-devsite/firestore_lite.writebatch.md create mode 100644 docs-devsite/functions.functions.md create mode 100644 docs-devsite/functions.functionserror.md create mode 100644 docs-devsite/functions.httpscallableoptions.md create mode 100644 docs-devsite/functions.httpscallableresult.md create mode 100644 docs-devsite/functions.md create mode 100644 docs-devsite/index.md create mode 100644 docs-devsite/installations.installations.md create mode 100644 docs-devsite/installations.md create mode 100644 docs-devsite/messaging.md create mode 100644 docs-devsite/messaging_.fcmoptions.md create mode 100644 docs-devsite/messaging_.gettokenoptions.md create mode 100644 docs-devsite/messaging_.md create mode 100644 docs-devsite/messaging_.messagepayload.md create mode 100644 docs-devsite/messaging_.messaging.md create mode 100644 docs-devsite/messaging_.notificationpayload.md create mode 100644 docs-devsite/messaging_sw.fcmoptions.md create mode 100644 docs-devsite/messaging_sw.gettokenoptions.md create mode 100644 docs-devsite/messaging_sw.md create mode 100644 docs-devsite/messaging_sw.messagepayload.md create mode 100644 docs-devsite/messaging_sw.messaging.md create mode 100644 docs-devsite/messaging_sw.notificationpayload.md create mode 100644 docs-devsite/performance.firebaseperformance.md create mode 100644 docs-devsite/performance.md create mode 100644 docs-devsite/performance.performancesettings.md create mode 100644 docs-devsite/performance.performancetrace.md create mode 100644 docs-devsite/remote-config.md create mode 100644 docs-devsite/remote-config.remoteconfig.md create mode 100644 docs-devsite/remote-config.remoteconfigsettings.md create mode 100644 docs-devsite/remote-config.value.md create mode 100644 docs-devsite/storage.firebasestorage.md create mode 100644 docs-devsite/storage.fullmetadata.md create mode 100644 docs-devsite/storage.listoptions.md create mode 100644 docs-devsite/storage.listresult.md create mode 100644 docs-devsite/storage.md create mode 100644 docs-devsite/storage.settablemetadata.md create mode 100644 docs-devsite/storage.storageerror.md create mode 100644 docs-devsite/storage.storageobserver.md create mode 100644 docs-devsite/storage.storagereference.md create mode 100644 docs-devsite/storage.uploadmetadata.md create mode 100644 docs-devsite/storage.uploadresult.md create mode 100644 docs-devsite/storage.uploadtask.md create mode 100644 docs-devsite/storage.uploadtasksnapshot.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 0c5b9da0f5e..7f2162988ab 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -99,4 +99,4 @@ scripts/docgen/content-sources/ @egilmorez @firebase/jssdk-global-approvers docs-devsite/ @egilmorez @markarndt # Changeset -.changeset @egilmorez @firebase/jssdk-changeset-approvers @firebase/firestore-js-team @firebase/jssdk-global-approvers \ No newline at end of file +.changeset @firebase/jssdk-changeset-approvers @firebase/firestore-js-team @firebase/jssdk-global-approvers \ No newline at end of file diff --git a/common/api-review/auth.api.md b/common/api-review/auth.api.md index 045b64bcf19..cf25749656c 100644 --- a/common/api-review/auth.api.md +++ b/common/api-review/auth.api.md @@ -103,14 +103,14 @@ export class AuthCredential { protected constructor( providerId: string, signInMethod: string); - // Warning: (ae-forgotten-export) The symbol "AuthInternal" needs to be exported by the entry point index.d.ts - // Warning: (ae-forgotten-export) The symbol "PhoneOrOauthTokenResponse" needs to be exported by the entry point index.d.ts + // Warning: (ae-forgotten-export) The symbol "AuthInternal" needs to be exported by the entry point index.doc.d.ts + // Warning: (ae-forgotten-export) The symbol "PhoneOrOauthTokenResponse" needs to be exported by the entry point index.doc.d.ts // // @internal (undocumented) _getIdTokenResponse(_auth: AuthInternal): Promise; // @internal (undocumented) _getReauthenticationResolver(_auth: AuthInternal): Promise; - // Warning: (ae-forgotten-export) The symbol "IdTokenResponse" needs to be exported by the entry point index.d.ts + // Warning: (ae-forgotten-export) The symbol "IdTokenResponse" needs to be exported by the entry point index.doc.d.ts // // @internal (undocumented) _linkToIdToken(_auth: AuthInternal, _idToken: string): Promise; @@ -283,6 +283,9 @@ export function connectAuthEmulator(auth: Auth, url: string, options?: { disableWarnings: boolean; }): void; +// @public +export const cordovaPopupRedirectResolver: PopupRedirectResolver; + // @public export function createUserWithEmailAndPassword(auth: Auth, email: string, password: string): Promise; @@ -346,7 +349,7 @@ export interface EmulatorConfig { export { ErrorFn } -// Warning: (ae-forgotten-export) The symbol "BaseOAuthProvider" needs to be exported by the entry point index.d.ts +// Warning: (ae-forgotten-export) The symbol "BaseOAuthProvider" needs to be exported by the entry point index.doc.d.ts // // @public export class FacebookAuthProvider extends BaseOAuthProvider { @@ -381,6 +384,9 @@ export function getIdTokenResult(user: User, forceRefresh?: boolean): Promise; @@ -490,7 +496,7 @@ export type NextOrObserver = NextFn | Observer; export class OAuthCredential extends AuthCredential { accessToken?: string; static fromJSON(json: string | object): OAuthCredential | null; - // Warning: (ae-forgotten-export) The symbol "OAuthCredentialParams" needs to be exported by the entry point index.d.ts + // Warning: (ae-forgotten-export) The symbol "OAuthCredentialParams" needs to be exported by the entry point index.doc.d.ts // // @internal (undocumented) static _fromParams(params: OAuthCredentialParams): OAuthCredential; @@ -568,7 +574,7 @@ export class PhoneAuthCredential extends AuthCredential { _getReauthenticationResolver(auth: AuthInternal): Promise; // @internal (undocumented) _linkToIdToken(auth: AuthInternal, idToken: string): Promise; - // Warning: (ae-forgotten-export) The symbol "SignInWithPhoneNumberRequest" needs to be exported by the entry point index.d.ts + // Warning: (ae-forgotten-export) The symbol "SignInWithPhoneNumberRequest" needs to be exported by the entry point index.doc.d.ts // // @internal (undocumented) _makeVerificationRequest(): SignInWithPhoneNumberRequest; @@ -647,6 +653,9 @@ export interface ReactNativeAsyncStorage { setItem(key: string, value: string): Promise; } +// @public +export const reactNativeLocalPersistence: Persistence; + // @public export function reauthenticateWithCredential(user: User, credential: AuthCredential): Promise; @@ -665,13 +674,13 @@ export interface RecaptchaParameters { [key: string]: any; } -// Warning: (ae-forgotten-export) The symbol "ApplicationVerifierInternal" needs to be exported by the entry point index.d.ts +// Warning: (ae-forgotten-export) The symbol "ApplicationVerifierInternal" needs to be exported by the entry point index.doc.d.ts // // @public export class RecaptchaVerifier implements ApplicationVerifierInternal { constructor(containerOrId: HTMLElement | string, parameters: RecaptchaParameters, authExtern: Auth); clear(): void; - // Warning: (ae-forgotten-export) The symbol "ReCaptchaLoader" needs to be exported by the entry point index.d.ts + // Warning: (ae-forgotten-export) The symbol "ReCaptchaLoader" needs to be exported by the entry point index.doc.d.ts // // @internal (undocumented) readonly _recaptchaLoader: ReCaptchaLoader; @@ -685,7 +694,7 @@ export class RecaptchaVerifier implements ApplicationVerifierInternal { // @public export function reload(user: User): Promise; -// Warning: (ae-forgotten-export) The symbol "FederatedAuthProvider" needs to be exported by the entry point index.d.ts +// Warning: (ae-forgotten-export) The symbol "FederatedAuthProvider" needs to be exported by the entry point index.doc.d.ts // // @public export class SAMLAuthProvider extends FederatedAuthProvider { diff --git a/docs-devsite/analytics.analytics.md b/docs-devsite/analytics.analytics.md new file mode 100644 index 00000000000..dcf0038f2d9 --- /dev/null +++ b/docs-devsite/analytics.analytics.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Analytics interface +An instance of Firebase Analytics. + +Signature: + +```typescript +export interface Analytics +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [app](./analytics.analytics.md#analyticsapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this [Analytics](./analytics.analytics.md#analytics_interface) instance is associated with. | + +## Analytics.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this [Analytics](./analytics.analytics.md#analytics_interface) instance is associated with. + +Signature: + +```typescript +app: FirebaseApp; +``` diff --git a/docs-devsite/analytics.analyticscalloptions.md b/docs-devsite/analytics.analyticscalloptions.md new file mode 100644 index 00000000000..d89863bcfa6 --- /dev/null +++ b/docs-devsite/analytics.analyticscalloptions.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AnalyticsCallOptions interface +Additional options that can be passed to Analytics method calls such as `logEvent`, etc. + +Signature: + +```typescript +export interface AnalyticsCallOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [global](./analytics.analyticscalloptions.md#analyticscalloptionsglobal) | boolean | If true, this config or event call applies globally to all Google Analytics properties on the page. | + +## AnalyticsCallOptions.global + +If true, this config or event call applies globally to all Google Analytics properties on the page. + +Signature: + +```typescript +global: boolean; +``` diff --git a/docs-devsite/analytics.analyticssettings.md b/docs-devsite/analytics.analyticssettings.md new file mode 100644 index 00000000000..3ee67d8456d --- /dev/null +++ b/docs-devsite/analytics.analyticssettings.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AnalyticsSettings interface +[Analytics](./analytics.analytics.md#analytics_interface) instance initialization options. + +Signature: + +```typescript +export interface AnalyticsSettings +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [config](./analytics.analyticssettings.md#analyticssettingsconfig) | [GtagConfigParams](./analytics.gtagconfigparams.md#gtagconfigparams_interface) \| [EventParams](./analytics.eventparams.md#eventparams_interface) | Params to be passed in the initial gtag config call during Firebase Analytics initialization. | + +## AnalyticsSettings.config + +Params to be passed in the initial `gtag` config call during Firebase Analytics initialization. + +Signature: + +```typescript +config?: GtagConfigParams | EventParams; +``` diff --git a/docs-devsite/analytics.consentsettings.md b/docs-devsite/analytics.consentsettings.md new file mode 100644 index 00000000000..975d51d8bc6 --- /dev/null +++ b/docs-devsite/analytics.consentsettings.md @@ -0,0 +1,79 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ConsentSettings interface +Consent status settings for each consent type. For more information, see [the GA4 reference documentation for consent state and consent types](https://developers.google.com/tag-platform/tag-manager/templates/consent-apis). + +Signature: + +```typescript +export interface ConsentSettings +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [ad\_storage](./analytics.consentsettings.md#consentsettingsad_storage) | [ConsentStatusString](./analytics.md#consentstatusstring) | Enables storage, such as cookies, related to advertising | +| [analytics\_storage](./analytics.consentsettings.md#consentsettingsanalytics_storage) | [ConsentStatusString](./analytics.md#consentstatusstring) | Enables storage, such as cookies, related to analytics (for example, visit duration) | +| [functionality\_storage](./analytics.consentsettings.md#consentsettingsfunctionality_storage) | [ConsentStatusString](./analytics.md#consentstatusstring) | Enables storage that supports the functionality of the website or app such as language settings | +| [personalization\_storage](./analytics.consentsettings.md#consentsettingspersonalization_storage) | [ConsentStatusString](./analytics.md#consentstatusstring) | Enables storage related to personalization such as video recommendations | +| [security\_storage](./analytics.consentsettings.md#consentsettingssecurity_storage) | [ConsentStatusString](./analytics.md#consentstatusstring) | Enables storage related to security such as authentication functionality, fraud prevention, and other user protection. | + +## ConsentSettings.ad\_storage + +Enables storage, such as cookies, related to advertising + +Signature: + +```typescript +ad_storage?: ConsentStatusString; +``` + +## ConsentSettings.analytics\_storage + +Enables storage, such as cookies, related to analytics (for example, visit duration) + +Signature: + +```typescript +analytics_storage?: ConsentStatusString; +``` + +## ConsentSettings.functionality\_storage + +Enables storage that supports the functionality of the website or app such as language settings + +Signature: + +```typescript +functionality_storage?: ConsentStatusString; +``` + +## ConsentSettings.personalization\_storage + +Enables storage related to personalization such as video recommendations + +Signature: + +```typescript +personalization_storage?: ConsentStatusString; +``` + +## ConsentSettings.security\_storage + +Enables storage related to security such as authentication functionality, fraud prevention, and other user protection. + +Signature: + +```typescript +security_storage?: ConsentStatusString; +``` diff --git a/docs-devsite/analytics.controlparams.md b/docs-devsite/analytics.controlparams.md new file mode 100644 index 00000000000..d7dfea1460c --- /dev/null +++ b/docs-devsite/analytics.controlparams.md @@ -0,0 +1,60 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ControlParams interface +Standard `gtag.js` control parameters. For more information, see [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export interface ControlParams +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [event\_callback](./analytics.controlparams.md#controlparamsevent_callback) | () => void | | +| [event\_timeout](./analytics.controlparams.md#controlparamsevent_timeout) | number | | +| [groups](./analytics.controlparams.md#controlparamsgroups) | string \| string\[\] | | +| [send\_to](./analytics.controlparams.md#controlparamssend_to) | string \| string\[\] | | + +## ControlParams.event\_callback + +Signature: + +```typescript +event_callback?: () => void; +``` + +## ControlParams.event\_timeout + +Signature: + +```typescript +event_timeout?: number; +``` + +## ControlParams.groups + +Signature: + +```typescript +groups?: string | string[]; +``` + +## ControlParams.send\_to + +Signature: + +```typescript +send_to?: string | string[]; +``` diff --git a/docs-devsite/analytics.customparams.md b/docs-devsite/analytics.customparams.md new file mode 100644 index 00000000000..37ac6964477 --- /dev/null +++ b/docs-devsite/analytics.customparams.md @@ -0,0 +1,19 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# CustomParams interface +Any custom params the user may pass to `gtag`. + +Signature: + +```typescript +export interface CustomParams +``` diff --git a/docs-devsite/analytics.eventparams.md b/docs-devsite/analytics.eventparams.md new file mode 100644 index 00000000000..266b8d3e85e --- /dev/null +++ b/docs-devsite/analytics.eventparams.md @@ -0,0 +1,316 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# EventParams interface +Standard `gtag.js` event parameters. For more information, see [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export interface EventParams +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [affiliation](./analytics.eventparams.md#eventparamsaffiliation) | string | | +| [checkout\_option](./analytics.eventparams.md#eventparamscheckout_option) | string | | +| [checkout\_step](./analytics.eventparams.md#eventparamscheckout_step) | number | | +| [content\_type](./analytics.eventparams.md#eventparamscontent_type) | string | | +| [coupon](./analytics.eventparams.md#eventparamscoupon) | string | | +| [currency](./analytics.eventparams.md#eventparamscurrency) | string | | +| [description](./analytics.eventparams.md#eventparamsdescription) | string | | +| [event\_category](./analytics.eventparams.md#eventparamsevent_category) | string | | +| [event\_label](./analytics.eventparams.md#eventparamsevent_label) | string | | +| [fatal](./analytics.eventparams.md#eventparamsfatal) | boolean | | +| [firebase\_screen\_class](./analytics.eventparams.md#eventparamsfirebase_screen_class) | string | Firebase-specific. Use to log a screen_class to Firebase Analytics. | +| [firebase\_screen](./analytics.eventparams.md#eventparamsfirebase_screen) | string | Firebase-specific. Use to log a screen_name to Firebase Analytics. | +| [item\_id](./analytics.eventparams.md#eventparamsitem_id) | string | | +| [item\_list\_id](./analytics.eventparams.md#eventparamsitem_list_id) | string | | +| [item\_list\_name](./analytics.eventparams.md#eventparamsitem_list_name) | string | | +| [items](./analytics.eventparams.md#eventparamsitems) | [Item](./analytics.item.md#item_interface)\[\] | | +| [method](./analytics.eventparams.md#eventparamsmethod) | string | | +| [number](./analytics.eventparams.md#eventparamsnumber) | string | | +| [page\_location](./analytics.eventparams.md#eventparamspage_location) | string | | +| [page\_path](./analytics.eventparams.md#eventparamspage_path) | string | | +| [page\_title](./analytics.eventparams.md#eventparamspage_title) | string | | +| [payment\_type](./analytics.eventparams.md#eventparamspayment_type) | string | | +| [promotion\_id](./analytics.eventparams.md#eventparamspromotion_id) | string | | +| [promotion\_name](./analytics.eventparams.md#eventparamspromotion_name) | string | | +| [promotions](./analytics.eventparams.md#eventparamspromotions) | [Promotion](./analytics.promotion.md#promotion_interface)\[\] | | +| [screen\_name](./analytics.eventparams.md#eventparamsscreen_name) | string | | +| [search\_term](./analytics.eventparams.md#eventparamssearch_term) | string | | +| [shipping\_tier](./analytics.eventparams.md#eventparamsshipping_tier) | string | | +| [shipping](./analytics.eventparams.md#eventparamsshipping) | [Currency](./analytics.md#currency) | | +| [tax](./analytics.eventparams.md#eventparamstax) | [Currency](./analytics.md#currency) | | +| [transaction\_id](./analytics.eventparams.md#eventparamstransaction_id) | string | | +| [value](./analytics.eventparams.md#eventparamsvalue) | number | | + +## EventParams.affiliation + +Signature: + +```typescript +affiliation?: string; +``` + +## EventParams.checkout\_option + +Signature: + +```typescript +checkout_option?: string; +``` + +## EventParams.checkout\_step + +Signature: + +```typescript +checkout_step?: number; +``` + +## EventParams.content\_type + +Signature: + +```typescript +content_type?: string; +``` + +## EventParams.coupon + +Signature: + +```typescript +coupon?: string; +``` + +## EventParams.currency + +Signature: + +```typescript +currency?: string; +``` + +## EventParams.description + +Signature: + +```typescript +description?: string; +``` + +## EventParams.event\_category + +Signature: + +```typescript +event_category?: string; +``` + +## EventParams.event\_label + +Signature: + +```typescript +event_label?: string; +``` + +## EventParams.fatal + +Signature: + +```typescript +fatal?: boolean; +``` + +## EventParams.firebase\_screen\_class + +Firebase-specific. Use to log a `screen_class` to Firebase Analytics. + +Signature: + +```typescript +firebase_screen_class?: string; +``` + +## EventParams.firebase\_screen + +Firebase-specific. Use to log a `screen_name` to Firebase Analytics. + +Signature: + +```typescript +firebase_screen?: string; +``` + +## EventParams.item\_id + +Signature: + +```typescript +item_id?: string; +``` + +## EventParams.item\_list\_id + +Signature: + +```typescript +item_list_id?: string; +``` + +## EventParams.item\_list\_name + +Signature: + +```typescript +item_list_name?: string; +``` + +## EventParams.items + +Signature: + +```typescript +items?: Item[]; +``` + +## EventParams.method + +Signature: + +```typescript +method?: string; +``` + +## EventParams.number + +Signature: + +```typescript +number?: string; +``` + +## EventParams.page\_location + +Signature: + +```typescript +page_location?: string; +``` + +## EventParams.page\_path + +Signature: + +```typescript +page_path?: string; +``` + +## EventParams.page\_title + +Signature: + +```typescript +page_title?: string; +``` + +## EventParams.payment\_type + +Signature: + +```typescript +payment_type?: string; +``` + +## EventParams.promotion\_id + +Signature: + +```typescript +promotion_id?: string; +``` + +## EventParams.promotion\_name + +Signature: + +```typescript +promotion_name?: string; +``` + +## EventParams.promotions + +Signature: + +```typescript +promotions?: Promotion[]; +``` + +## EventParams.screen\_name + +Signature: + +```typescript +screen_name?: string; +``` + +## EventParams.search\_term + +Signature: + +```typescript +search_term?: string; +``` + +## EventParams.shipping\_tier + +Signature: + +```typescript +shipping_tier?: string; +``` + +## EventParams.shipping + +Signature: + +```typescript +shipping?: Currency; +``` + +## EventParams.tax + +Signature: + +```typescript +tax?: Currency; +``` + +## EventParams.transaction\_id + +Signature: + +```typescript +transaction_id?: string; +``` + +## EventParams.value + +Signature: + +```typescript +value?: number; +``` diff --git a/docs-devsite/analytics.gtagconfigparams.md b/docs-devsite/analytics.gtagconfigparams.md new file mode 100644 index 00000000000..f5138b8b65e --- /dev/null +++ b/docs-devsite/analytics.gtagconfigparams.md @@ -0,0 +1,134 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# GtagConfigParams interface +A set of common Google Analytics config settings recognized by `gtag.js`. + +Signature: + +```typescript +export interface GtagConfigParams +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [allow\_ad\_personalization\_signals](./analytics.gtagconfigparams.md#gtagconfigparamsallow_ad_personalization_signals) | boolean | If set to false, disables all advertising personalization with gtag.js. See [Disable advertising features](https://developers.google.com/analytics/devguides/collection/ga4/display-features) | +| [allow\_google\_signals](./analytics.gtagconfigparams.md#gtagconfigparamsallow_google_signals) | boolean | If set to false, disables all advertising features with gtag.js. See [Disable advertising features](https://developers.google.com/analytics/devguides/collection/ga4/display-features) | +| [cookie\_domain](./analytics.gtagconfigparams.md#gtagconfigparamscookie_domain) | string | Defaults to auto. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) | +| [cookie\_expires](./analytics.gtagconfigparams.md#gtagconfigparamscookie_expires) | number | Defaults to 63072000 (two years, in seconds). See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) | +| [cookie\_flags](./analytics.gtagconfigparams.md#gtagconfigparamscookie_flags) | string | Appends additional flags to the cookie when set. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) | +| [cookie\_prefix](./analytics.gtagconfigparams.md#gtagconfigparamscookie_prefix) | string | Defaults to _ga. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) | +| [cookie\_update](./analytics.gtagconfigparams.md#gtagconfigparamscookie_update) | boolean | If set to true, will update cookies on each page load. Defaults to true. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) | +| [page\_location](./analytics.gtagconfigparams.md#gtagconfigparamspage_location) | string | The URL of the page. See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view) | +| [page\_title](./analytics.gtagconfigparams.md#gtagconfigparamspage_title) | string | The title of the page. See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view) | +| [send\_page\_view](./analytics.gtagconfigparams.md#gtagconfigparamssend_page_view) | boolean | Whether or not a page view should be sent. If set to true (default), a page view is automatically sent upon initialization of analytics. See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view) | + +## GtagConfigParams.allow\_ad\_personalization\_signals + +If set to false, disables all advertising personalization with `gtag.js`. See [Disable advertising features](https://developers.google.com/analytics/devguides/collection/ga4/display-features) + +Signature: + +```typescript +'allow_ad_personalization_signals'?: boolean; +``` + +## GtagConfigParams.allow\_google\_signals + +If set to false, disables all advertising features with `gtag.js`. See [Disable advertising features](https://developers.google.com/analytics/devguides/collection/ga4/display-features) + +Signature: + +```typescript +'allow_google_signals'?: boolean; +``` + +## GtagConfigParams.cookie\_domain + +Defaults to `auto`. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) + +Signature: + +```typescript +'cookie_domain'?: string; +``` + +## GtagConfigParams.cookie\_expires + +Defaults to 63072000 (two years, in seconds). See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) + +Signature: + +```typescript +'cookie_expires'?: number; +``` + +## GtagConfigParams.cookie\_flags + +Appends additional flags to the cookie when set. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) + +Signature: + +```typescript +'cookie_flags'?: string; +``` + +## GtagConfigParams.cookie\_prefix + +Defaults to `_ga`. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) + +Signature: + +```typescript +'cookie_prefix'?: string; +``` + +## GtagConfigParams.cookie\_update + +If set to true, will update cookies on each page load. Defaults to true. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) + +Signature: + +```typescript +'cookie_update'?: boolean; +``` + +## GtagConfigParams.page\_location + +The URL of the page. See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view) + +Signature: + +```typescript +'page_location'?: string; +``` + +## GtagConfigParams.page\_title + +The title of the page. See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view) + +Signature: + +```typescript +'page_title'?: string; +``` + +## GtagConfigParams.send\_page\_view + +Whether or not a page view should be sent. If set to true (default), a page view is automatically sent upon initialization of analytics. See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view) + +Signature: + +```typescript +'send_page_view'?: boolean; +``` diff --git a/docs-devsite/analytics.item.md b/docs-devsite/analytics.item.md new file mode 100644 index 00000000000..5c853918edb --- /dev/null +++ b/docs-devsite/analytics.item.md @@ -0,0 +1,278 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Item interface +Standard Google Analytics `Item` type. + +Signature: + +```typescript +export interface Item +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [affiliation](./analytics.item.md#itemaffiliation) | string | | +| [brand](./analytics.item.md#itembrand) | string | | +| [category](./analytics.item.md#itemcategory) | string | | +| [coupon](./analytics.item.md#itemcoupon) | string | | +| [creative\_name](./analytics.item.md#itemcreative_name) | string | | +| [creative\_slot](./analytics.item.md#itemcreative_slot) | string | | +| [discount](./analytics.item.md#itemdiscount) | [Currency](./analytics.md#currency) | | +| [id](./analytics.item.md#itemid) | string | | +| [index](./analytics.item.md#itemindex) | number | | +| [item\_brand](./analytics.item.md#itemitem_brand) | string | | +| [item\_category](./analytics.item.md#itemitem_category) | string | | +| [item\_category2](./analytics.item.md#itemitem_category2) | string | | +| [item\_category3](./analytics.item.md#itemitem_category3) | string | | +| [item\_category4](./analytics.item.md#itemitem_category4) | string | | +| [item\_category5](./analytics.item.md#itemitem_category5) | string | | +| [item\_id](./analytics.item.md#itemitem_id) | string | | +| [item\_list\_id](./analytics.item.md#itemitem_list_id) | string | | +| [item\_list\_name](./analytics.item.md#itemitem_list_name) | string | | +| [item\_name](./analytics.item.md#itemitem_name) | string | | +| [item\_variant](./analytics.item.md#itemitem_variant) | string | | +| [location\_id](./analytics.item.md#itemlocation_id) | string | | +| [name](./analytics.item.md#itemname) | string | | +| [price](./analytics.item.md#itemprice) | [Currency](./analytics.md#currency) | | +| [promotion\_id](./analytics.item.md#itempromotion_id) | string | | +| [promotion\_name](./analytics.item.md#itempromotion_name) | string | | +| [quantity](./analytics.item.md#itemquantity) | number | | + +## Item.affiliation + +Signature: + +```typescript +affiliation?: string; +``` + +## Item.brand + +> Warning: This API is now obsolete. +> +> Use item\_brand instead. +> + +Signature: + +```typescript +brand?: string; +``` + +## Item.category + +> Warning: This API is now obsolete. +> +> Use item\_category instead. +> + +Signature: + +```typescript +category?: string; +``` + +## Item.coupon + +Signature: + +```typescript +coupon?: string; +``` + +## Item.creative\_name + +Signature: + +```typescript +creative_name?: string; +``` + +## Item.creative\_slot + +Signature: + +```typescript +creative_slot?: string; +``` + +## Item.discount + +Signature: + +```typescript +discount?: Currency; +``` + +## Item.id + +> Warning: This API is now obsolete. +> +> Use item\_id instead. +> + +Signature: + +```typescript +id?: string; +``` + +## Item.index + +Signature: + +```typescript +index?: number; +``` + +## Item.item\_brand + +Signature: + +```typescript +item_brand?: string; +``` + +## Item.item\_category + +Signature: + +```typescript +item_category?: string; +``` + +## Item.item\_category2 + +Signature: + +```typescript +item_category2?: string; +``` + +## Item.item\_category3 + +Signature: + +```typescript +item_category3?: string; +``` + +## Item.item\_category4 + +Signature: + +```typescript +item_category4?: string; +``` + +## Item.item\_category5 + +Signature: + +```typescript +item_category5?: string; +``` + +## Item.item\_id + +Signature: + +```typescript +item_id?: string; +``` + +## Item.item\_list\_id + +Signature: + +```typescript +item_list_id?: string; +``` + +## Item.item\_list\_name + +Signature: + +```typescript +item_list_name?: string; +``` + +## Item.item\_name + +Signature: + +```typescript +item_name?: string; +``` + +## Item.item\_variant + +Signature: + +```typescript +item_variant?: string; +``` + +## Item.location\_id + +Signature: + +```typescript +location_id?: string; +``` + +## Item.name + +> Warning: This API is now obsolete. +> +> Use item\_name instead. +> + +Signature: + +```typescript +name?: string; +``` + +## Item.price + +Signature: + +```typescript +price?: Currency; +``` + +## Item.promotion\_id + +Signature: + +```typescript +promotion_id?: string; +``` + +## Item.promotion\_name + +Signature: + +```typescript +promotion_name?: string; +``` + +## Item.quantity + +Signature: + +```typescript +quantity?: number; +``` diff --git a/docs-devsite/analytics.md b/docs-devsite/analytics.md new file mode 100644 index 00000000000..bd6e4b69351 --- /dev/null +++ b/docs-devsite/analytics.md @@ -0,0 +1,991 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# analytics package +Firebase Analytics + +## Functions + +| Function | Description | +| --- | --- | +| function(app...) | +| [getAnalytics(app)](./analytics.md#getanalytics) | Returns an [Analytics](./analytics.analytics.md#analytics_interface) instance for the given app. | +| [initializeAnalytics(app, options)](./analytics.md#initializeanalytics) | Returns an [Analytics](./analytics.analytics.md#analytics_interface) instance for the given app. | +| function(analyticsInstance...) | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.See [Track Screenviews](https://firebase.google.com/docs/analytics/screenviews). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.See [Measure exceptions](https://developers.google.com/analytics/devguides/collection/ga4/exceptions). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view). | +| [setAnalyticsCollectionEnabled(analyticsInstance, enabled)](./analytics.md#setanalyticscollectionenabled) | Sets whether Google Analytics collection is enabled for this app on this device. Sets global window['ga-disable-analyticsId'] = true; | +| [setCurrentScreen(analyticsInstance, screenName, options)](./analytics.md#setcurrentscreen) | Use gtag config command to set screen_name. | +| [setUserId(analyticsInstance, id, options)](./analytics.md#setuserid) | Use gtag config command to set user_id. | +| [setUserProperties(analyticsInstance, properties, options)](./analytics.md#setuserproperties) | Use gtag config command to set all params specified. | +| function() | +| [isSupported()](./analytics.md#issupported) | This is a public static method provided to users that wraps four different checks:1. Check if it's not a browser extension environment. 2. Check if cookies are enabled in current browser. 3. Check if IndexedDB is supported by the browser environment. 4. Check if the current browser context is valid for using IndexedDB.open(). | +| function(consentSettings...) | +| [setConsent(consentSettings)](./analytics.md#setconsent) | Sets the applicable end user consent state for this web app across all gtag references once Firebase Analytics is initialized.Use the [ConsentSettings](./analytics.consentsettings.md#consentsettings_interface) to specify individual consent type values. By default consent types are set to "granted". | +| function(customParams...) | +| [setDefaultEventParameters(customParams)](./analytics.md#setdefaulteventparameters) | Adds data that will be set on every event logged from the SDK, including automatic ones. With gtag's "set" command, the values passed persist on the current page and are passed with all subsequent events. | +| function(options...) | +| [settings(options)](./analytics.md#settings) | Configures Firebase Analytics to use custom gtag or dataLayer names. Intended to be used if gtag.js script has been installed on this page independently of Firebase Analytics, and is using non-default names for either the gtag function or for dataLayer. Must be called before calling getAnalytics() or it won't have any effect. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [Analytics](./analytics.analytics.md#analytics_interface) | An instance of Firebase Analytics. | +| [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | Additional options that can be passed to Analytics method calls such as logEvent, etc. | +| [AnalyticsSettings](./analytics.analyticssettings.md#analyticssettings_interface) | [Analytics](./analytics.analytics.md#analytics_interface) instance initialization options. | +| [ConsentSettings](./analytics.consentsettings.md#consentsettings_interface) | Consent status settings for each consent type. For more information, see [the GA4 reference documentation for consent state and consent types](https://developers.google.com/tag-platform/tag-manager/templates/consent-apis). | +| [ControlParams](./analytics.controlparams.md#controlparams_interface) | Standard gtag.js control parameters. For more information, see [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [CustomParams](./analytics.customparams.md#customparams_interface) | Any custom params the user may pass to gtag. | +| [EventParams](./analytics.eventparams.md#eventparams_interface) | Standard gtag.js event parameters. For more information, see [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [GtagConfigParams](./analytics.gtagconfigparams.md#gtagconfigparams_interface) | A set of common Google Analytics config settings recognized by gtag.js. | +| [Item](./analytics.item.md#item_interface) | Standard Google Analytics Item type. | +| [Promotion](./analytics.promotion.md#promotion_interface) | Field previously used by some Google Analytics events. | +| [SettingsOptions](./analytics.settingsoptions.md#settingsoptions_interface) | Specifies custom options for your Firebase Analytics instance. You must set these before initializing firebase.analytics(). | + +## Type Aliases + +| Type Alias | Description | +| --- | --- | +| [ConsentStatusString](./analytics.md#consentstatusstring) | Whether a particular consent type has been granted or denied. | +| [Currency](./analytics.md#currency) | Standard Google Analytics currency type. | +| [CustomEventName](./analytics.md#customeventname) | Any custom event name string not in the standard list of recommended event names. | +| [EventNameString](./analytics.md#eventnamestring) | Type for standard Google Analytics event names. logEvent also accepts any custom string and interprets it as a custom event name. | + +## getAnalytics() + +Returns an [Analytics](./analytics.analytics.md#analytics_interface) instance for the given app. + +Signature: + +```typescript +export declare function getAnalytics(app?: FirebaseApp): Analytics; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to use. | + +Returns: + +[Analytics](./analytics.analytics.md#analytics_interface) + +## initializeAnalytics() + +Returns an [Analytics](./analytics.analytics.md#analytics_interface) instance for the given app. + +Signature: + +```typescript +export declare function initializeAnalytics(app: FirebaseApp, options?: AnalyticsSettings): Analytics; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to use. | +| options | [AnalyticsSettings](./analytics.analyticssettings.md#analyticssettings_interface) | | + +Returns: + +[Analytics](./analytics.analytics.md#analytics_interface) + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'add_payment_info', eventParams?: { + coupon?: EventParams['coupon']; + currency?: EventParams['currency']; + items?: EventParams['items']; + payment_type?: EventParams['payment_type']; + value?: EventParams['value']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'add\_payment\_info' | | +| eventParams | { coupon?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['coupon'\]; currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; payment\_type?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['payment\_type'\]; value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'purchase' | 'refund', eventParams?: { + value?: EventParams['value']; + currency?: EventParams['currency']; + transaction_id: EventParams['transaction_id']; + tax?: EventParams['tax']; + shipping?: EventParams['shipping']; + items?: EventParams['items']; + coupon?: EventParams['coupon']; + affiliation?: EventParams['affiliation']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'purchase' \| 'refund' | | +| eventParams | { value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; transaction\_id: [EventParams](./analytics.eventparams.md#eventparams_interface)\['transaction\_id'\]; tax?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['tax'\]; shipping?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['shipping'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; coupon?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['coupon'\]; affiliation?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['affiliation'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +See [Track Screenviews](https://firebase.google.com/docs/analytics/screenviews). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'screen_view', eventParams?: { + firebase_screen: EventParams['firebase_screen']; + firebase_screen_class: EventParams['firebase_screen_class']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'screen\_view' | | +| eventParams | { firebase\_screen: [EventParams](./analytics.eventparams.md#eventparams_interface)\['firebase\_screen'\]; firebase\_screen\_class: [EventParams](./analytics.eventparams.md#eventparams_interface)\['firebase\_screen\_class'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'search' | 'view_search_results', eventParams?: { + search_term?: EventParams['search_term']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'search' \| 'view\_search\_results' | | +| eventParams | { search\_term?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['search\_term'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'select_content', eventParams?: { + content_type?: EventParams['content_type']; + item_id?: EventParams['item_id']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'select\_content' | | +| eventParams | { content\_type?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['content\_type'\]; item\_id?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['item\_id'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'select_item', eventParams?: { + items?: EventParams['items']; + item_list_name?: EventParams['item_list_name']; + item_list_id?: EventParams['item_list_id']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'select\_item' | | +| eventParams | { items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; item\_list\_name?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['item\_list\_name'\]; item\_list\_id?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['item\_list\_id'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'select_promotion' | 'view_promotion', eventParams?: { + items?: EventParams['items']; + promotion_id?: EventParams['promotion_id']; + promotion_name?: EventParams['promotion_name']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'select\_promotion' \| 'view\_promotion' | | +| eventParams | { items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; promotion\_id?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['promotion\_id'\]; promotion\_name?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['promotion\_name'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'set_checkout_option', eventParams?: { + checkout_step?: EventParams['checkout_step']; + checkout_option?: EventParams['checkout_option']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'set\_checkout\_option' | | +| eventParams | { checkout\_step?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['checkout\_step'\]; checkout\_option?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['checkout\_option'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'share', eventParams?: { + method?: EventParams['method']; + content_type?: EventParams['content_type']; + item_id?: EventParams['item_id']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'share' | | +| eventParams | { method?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['method'\]; content\_type?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['content\_type'\]; item\_id?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['item\_id'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'sign_up', eventParams?: { + method?: EventParams['method']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'sign\_up' | | +| eventParams | { method?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['method'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'timing_complete', eventParams?: { + name: string; + value: number; + event_category?: string; + event_label?: string; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'timing\_complete' | | +| eventParams | { name: string; value: number; event\_category?: string; event\_label?: string; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'add_shipping_info', eventParams?: { + coupon?: EventParams['coupon']; + currency?: EventParams['currency']; + items?: EventParams['items']; + shipping_tier?: EventParams['shipping_tier']; + value?: EventParams['value']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'add\_shipping\_info' | | +| eventParams | { coupon?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['coupon'\]; currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; shipping\_tier?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['shipping\_tier'\]; value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'view_cart' | 'view_item', eventParams?: { + currency?: EventParams['currency']; + items?: EventParams['items']; + value?: EventParams['value']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'view\_cart' \| 'view\_item' | | +| eventParams | { currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'view_item_list', eventParams?: { + items?: EventParams['items']; + item_list_name?: EventParams['item_list_name']; + item_list_id?: EventParams['item_list_id']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'view\_item\_list' | | +| eventParams | { items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; item\_list\_name?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['item\_list\_name'\]; item\_list\_id?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['item\_list\_id'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: CustomEventName, eventParams?: { + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | [CustomEventName](./analytics.md#customeventname)<T> | | +| eventParams | { \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'add_to_cart' | 'add_to_wishlist' | 'remove_from_cart', eventParams?: { + currency?: EventParams['currency']; + value?: EventParams['value']; + items?: EventParams['items']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'add\_to\_cart' \| 'add\_to\_wishlist' \| 'remove\_from\_cart' | | +| eventParams | { currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'begin_checkout', eventParams?: { + currency?: EventParams['currency']; + coupon?: EventParams['coupon']; + value?: EventParams['value']; + items?: EventParams['items']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'begin\_checkout' | | +| eventParams | { currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; coupon?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['coupon'\]; value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'checkout_progress', eventParams?: { + currency?: EventParams['currency']; + coupon?: EventParams['coupon']; + value?: EventParams['value']; + items?: EventParams['items']; + checkout_step?: EventParams['checkout_step']; + checkout_option?: EventParams['checkout_option']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'checkout\_progress' | | +| eventParams | { currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; coupon?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['coupon'\]; value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; checkout\_step?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['checkout\_step'\]; checkout\_option?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['checkout\_option'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +See [Measure exceptions](https://developers.google.com/analytics/devguides/collection/ga4/exceptions). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'exception', eventParams?: { + description?: EventParams['description']; + fatal?: EventParams['fatal']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'exception' | | +| eventParams | { description?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['description'\]; fatal?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['fatal'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'generate_lead', eventParams?: { + value?: EventParams['value']; + currency?: EventParams['currency']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'generate\_lead' | | +| eventParams | { value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'login', eventParams?: { + method?: EventParams['method']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'login' | | +| eventParams | { method?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['method'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'page_view', eventParams?: { + page_title?: string; + page_location?: string; + page_path?: string; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'page\_view' | | +| eventParams | { page\_title?: string; page\_location?: string; page\_path?: string; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## setAnalyticsCollectionEnabled() + +Sets whether Google Analytics collection is enabled for this app on this device. Sets global `window['ga-disable-analyticsId'] = true;` + +Signature: + +```typescript +export declare function setAnalyticsCollectionEnabled(analyticsInstance: Analytics, enabled: boolean): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | The [Analytics](./analytics.analytics.md#analytics_interface) instance. | +| enabled | boolean | If true, enables collection, if false, disables it. | + +Returns: + +void + +## setCurrentScreen() + +> Warning: This API is now obsolete. +> +> Use with `eventName` as 'screen\_view' and add relevant `eventParams`. See [Track Screenviews](https://firebase.google.com/docs/analytics/screenviews). +> + +Use gtag `config` command to set `screen_name`. + +Signature: + +```typescript +export declare function setCurrentScreen(analyticsInstance: Analytics, screenName: string, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | The [Analytics](./analytics.analytics.md#analytics_interface) instance. | +| screenName | string | Screen name to set. | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## setUserId() + +Use gtag `config` command to set `user_id`. + +Signature: + +```typescript +export declare function setUserId(analyticsInstance: Analytics, id: string | null, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | The [Analytics](./analytics.analytics.md#analytics_interface) instance. | +| id | string \| null | User ID to set. | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## setUserProperties() + +Use gtag `config` command to set all params specified. + +Signature: + +```typescript +export declare function setUserProperties(analyticsInstance: Analytics, properties: CustomParams, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| properties | [CustomParams](./analytics.customparams.md#customparams_interface) | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## isSupported() + +This is a public static method provided to users that wraps four different checks: + +1. Check if it's not a browser extension environment. 2. Check if cookies are enabled in current browser. 3. Check if IndexedDB is supported by the browser environment. 4. Check if the current browser context is valid for using `IndexedDB.open()`. + +Signature: + +```typescript +export declare function isSupported(): Promise; +``` +Returns: + +Promise<boolean> + +## setConsent() + +Sets the applicable end user consent state for this web app across all gtag references once Firebase Analytics is initialized. + +Use the [ConsentSettings](./analytics.consentsettings.md#consentsettings_interface) to specify individual consent type values. By default consent types are set to "granted". + +Signature: + +```typescript +export declare function setConsent(consentSettings: ConsentSettings): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| consentSettings | [ConsentSettings](./analytics.consentsettings.md#consentsettings_interface) | Maps the applicable end user consent state for gtag.js. | + +Returns: + +void + +## setDefaultEventParameters() + +Adds data that will be set on every event logged from the SDK, including automatic ones. With gtag's "set" command, the values passed persist on the current page and are passed with all subsequent events. + +Signature: + +```typescript +export declare function setDefaultEventParameters(customParams: CustomParams): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| customParams | [CustomParams](./analytics.customparams.md#customparams_interface) | Any custom params the user may pass to gtag.js. | + +Returns: + +void + +## settings() + +Configures Firebase Analytics to use custom `gtag` or `dataLayer` names. Intended to be used if `gtag.js` script has been installed on this page independently of Firebase Analytics, and is using non-default names for either the `gtag` function or for `dataLayer`. Must be called before calling `getAnalytics()` or it won't have any effect. + +Signature: + +```typescript +export declare function settings(options: SettingsOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| options | [SettingsOptions](./analytics.settingsoptions.md#settingsoptions_interface) | Custom gtag and dataLayer names. | + +Returns: + +void + +## ConsentStatusString + +Whether a particular consent type has been granted or denied. + +Signature: + +```typescript +export declare type ConsentStatusString = 'granted' | 'denied'; +``` + +## Currency + +Standard Google Analytics currency type. + +Signature: + +```typescript +export declare type Currency = string | number; +``` + +## CustomEventName + +Any custom event name string not in the standard list of recommended event names. + +Signature: + +```typescript +export declare type CustomEventName = T extends EventNameString ? never : T; +``` + +## EventNameString + +Type for standard Google Analytics event names. `logEvent` also accepts any custom string and interprets it as a custom event name. + +Signature: + +```typescript +export declare type EventNameString = 'add_payment_info' | 'add_shipping_info' | 'add_to_cart' | 'add_to_wishlist' | 'begin_checkout' | 'checkout_progress' | 'exception' | 'generate_lead' | 'login' | 'page_view' | 'purchase' | 'refund' | 'remove_from_cart' | 'screen_view' | 'search' | 'select_content' | 'select_item' | 'select_promotion' | 'set_checkout_option' | 'share' | 'sign_up' | 'timing_complete' | 'view_cart' | 'view_item' | 'view_item_list' | 'view_promotion' | 'view_search_results'; +``` diff --git a/docs-devsite/analytics.promotion.md b/docs-devsite/analytics.promotion.md new file mode 100644 index 00000000000..7e29e0335e4 --- /dev/null +++ b/docs-devsite/analytics.promotion.md @@ -0,0 +1,65 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Promotion interface +> Warning: This API is now obsolete. +> +> Use `Item` instead. +> + +Field previously used by some Google Analytics events. + +Signature: + +```typescript +export interface Promotion +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [creative\_name](./analytics.promotion.md#promotioncreative_name) | string | | +| [creative\_slot](./analytics.promotion.md#promotioncreative_slot) | string | | +| [id](./analytics.promotion.md#promotionid) | string | | +| [name](./analytics.promotion.md#promotionname) | string | | + +## Promotion.creative\_name + +Signature: + +```typescript +creative_name?: string; +``` + +## Promotion.creative\_slot + +Signature: + +```typescript +creative_slot?: string; +``` + +## Promotion.id + +Signature: + +```typescript +id?: string; +``` + +## Promotion.name + +Signature: + +```typescript +name?: string; +``` diff --git a/docs-devsite/analytics.settingsoptions.md b/docs-devsite/analytics.settingsoptions.md new file mode 100644 index 00000000000..e43152074d0 --- /dev/null +++ b/docs-devsite/analytics.settingsoptions.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# SettingsOptions interface +Specifies custom options for your Firebase Analytics instance. You must set these before initializing `firebase.analytics()`. + +Signature: + +```typescript +export interface SettingsOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [dataLayerName](./analytics.settingsoptions.md#settingsoptionsdatalayername) | string | Sets custom name for dataLayer array used by gtag.js. | +| [gtagName](./analytics.settingsoptions.md#settingsoptionsgtagname) | string | Sets custom name for gtag function. | + +## SettingsOptions.dataLayerName + +Sets custom name for `dataLayer` array used by `gtag.js`. + +Signature: + +```typescript +dataLayerName?: string; +``` + +## SettingsOptions.gtagName + +Sets custom name for `gtag` function. + +Signature: + +```typescript +gtagName?: string; +``` diff --git a/docs-devsite/app-check.appcheck.md b/docs-devsite/app-check.appcheck.md new file mode 100644 index 00000000000..a4cb809924d --- /dev/null +++ b/docs-devsite/app-check.appcheck.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AppCheck interface +The Firebase App Check service interface. + +Signature: + +```typescript +export interface AppCheck +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [app](./app-check.appcheck.md#appcheckapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this AppCheck instance is associated with. | + +## AppCheck.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `AppCheck` instance is associated with. + +Signature: + +```typescript +app: FirebaseApp; +``` diff --git a/docs-devsite/app-check.appcheckoptions.md b/docs-devsite/app-check.appcheckoptions.md new file mode 100644 index 00000000000..4d3630faa65 --- /dev/null +++ b/docs-devsite/app-check.appcheckoptions.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AppCheckOptions interface +Options for App Check initialization. + +Signature: + +```typescript +export interface AppCheckOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [isTokenAutoRefreshEnabled](./app-check.appcheckoptions.md#appcheckoptionsistokenautorefreshenabled) | boolean | If set to true, enables automatic background refresh of App Check token. | +| [provider](./app-check.appcheckoptions.md#appcheckoptionsprovider) | [CustomProvider](./app-check.customprovider.md#customprovider_class) \| [ReCaptchaV3Provider](./app-check.recaptchav3provider.md#recaptchav3provider_class) \| [ReCaptchaEnterpriseProvider](./app-check.recaptchaenterpriseprovider.md#recaptchaenterpriseprovider_class) | A reCAPTCHA V3 provider, reCAPTCHA Enterprise provider, or custom provider. | + +## AppCheckOptions.isTokenAutoRefreshEnabled + +If set to true, enables automatic background refresh of App Check token. + +Signature: + +```typescript +isTokenAutoRefreshEnabled?: boolean; +``` + +## AppCheckOptions.provider + +A reCAPTCHA V3 provider, reCAPTCHA Enterprise provider, or custom provider. + +Signature: + +```typescript +provider: CustomProvider | ReCaptchaV3Provider | ReCaptchaEnterpriseProvider; +``` diff --git a/docs-devsite/app-check.appchecktoken.md b/docs-devsite/app-check.appchecktoken.md new file mode 100644 index 00000000000..9cb71d78bbb --- /dev/null +++ b/docs-devsite/app-check.appchecktoken.md @@ -0,0 +1,44 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AppCheckToken interface +The token returned from an App Check provider. + +Signature: + +```typescript +export interface AppCheckToken +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [expireTimeMillis](./app-check.appchecktoken.md#appchecktokenexpiretimemillis) | number | The local timestamp after which the token will expire. | +| [token](./app-check.appchecktoken.md#appchecktokentoken) | string | | + +## AppCheckToken.expireTimeMillis + +The local timestamp after which the token will expire. + +Signature: + +```typescript +readonly expireTimeMillis: number; +``` + +## AppCheckToken.token + +Signature: + +```typescript +readonly token: string; +``` diff --git a/docs-devsite/app-check.appchecktokenresult.md b/docs-devsite/app-check.appchecktokenresult.md new file mode 100644 index 00000000000..185d60992c1 --- /dev/null +++ b/docs-devsite/app-check.appchecktokenresult.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AppCheckTokenResult interface +Result returned by `getToken()`. + +Signature: + +```typescript +export interface AppCheckTokenResult +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [token](./app-check.appchecktokenresult.md#appchecktokenresulttoken) | string | The token string in JWT format. | + +## AppCheckTokenResult.token + +The token string in JWT format. + +Signature: + +```typescript +readonly token: string; +``` diff --git a/docs-devsite/app-check.customprovider.md b/docs-devsite/app-check.customprovider.md new file mode 100644 index 00000000000..e00da1d7897 --- /dev/null +++ b/docs-devsite/app-check.customprovider.md @@ -0,0 +1,43 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# CustomProvider class +Custom provider class. + +Signature: + +```typescript +export declare class CustomProvider implements AppCheckProvider +``` +Implements: AppCheckProvider + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(\_customProviderOptions)](./app-check.customprovider.md#customproviderconstructor) | | Constructs a new instance of the CustomProvider class | + +## CustomProvider.(constructor) + +Constructs a new instance of the `CustomProvider` class + +Signature: + +```typescript +constructor(_customProviderOptions: CustomProviderOptions); +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| \_customProviderOptions | [CustomProviderOptions](./app-check.customprovideroptions.md#customprovideroptions_interface) | | + diff --git a/docs-devsite/app-check.customprovideroptions.md b/docs-devsite/app-check.customprovideroptions.md new file mode 100644 index 00000000000..c122e0476dd --- /dev/null +++ b/docs-devsite/app-check.customprovideroptions.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# CustomProviderOptions interface +Options when creating a [CustomProvider](./app-check.customprovider.md#customprovider_class). + +Signature: + +```typescript +export interface CustomProviderOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [getToken](./app-check.customprovideroptions.md#customprovideroptionsgettoken) | () => Promise<[AppCheckToken](./app-check.appchecktoken.md#appchecktoken_interface)> | Function to get an App Check token through a custom provider service. | + +## CustomProviderOptions.getToken + +Function to get an App Check token through a custom provider service. + +Signature: + +```typescript +getToken: () => Promise; +``` diff --git a/docs-devsite/app-check.md b/docs-devsite/app-check.md new file mode 100644 index 00000000000..b7895a05c96 --- /dev/null +++ b/docs-devsite/app-check.md @@ -0,0 +1,170 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# app-check package +Firebase App Check + +## Functions + +| Function | Description | +| --- | --- | +| function(app...) | +| [initializeAppCheck(app, options)](./app-check.md#initializeappcheck) | Activate App Check for the given app. Can be called only once per app. | +| function(appCheckInstance...) | +| [getToken(appCheckInstance, forceRefresh)](./app-check.md#gettoken) | Get the current App Check token. Attaches to the most recent in-flight request if one is present. Returns null if no token is present and no token requests are in-flight. | +| [onTokenChanged(appCheckInstance, observer)](./app-check.md#ontokenchanged) | Registers a listener to changes in the token state. There can be more than one listener registered at the same time for one or more App Check instances. The listeners call back on the UI thread whenever the current token associated with this App Check instance changes. | +| [onTokenChanged(appCheckInstance, onNext, onError, onCompletion)](./app-check.md#ontokenchanged) | Registers a listener to changes in the token state. There can be more than one listener registered at the same time for one or more App Check instances. The listeners call back on the UI thread whenever the current token associated with this App Check instance changes. | +| [setTokenAutoRefreshEnabled(appCheckInstance, isTokenAutoRefreshEnabled)](./app-check.md#settokenautorefreshenabled) | Set whether App Check will automatically refresh tokens as needed. | + +## Classes + +| Class | Description | +| --- | --- | +| [CustomProvider](./app-check.customprovider.md#customprovider_class) | Custom provider class. | +| [ReCaptchaEnterpriseProvider](./app-check.recaptchaenterpriseprovider.md#recaptchaenterpriseprovider_class) | App Check provider that can obtain a reCAPTCHA Enterprise token and exchange it for an App Check token. | +| [ReCaptchaV3Provider](./app-check.recaptchav3provider.md#recaptchav3provider_class) | App Check provider that can obtain a reCAPTCHA V3 token and exchange it for an App Check token. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [AppCheck](./app-check.appcheck.md#appcheck_interface) | The Firebase App Check service interface. | +| [AppCheckOptions](./app-check.appcheckoptions.md#appcheckoptions_interface) | Options for App Check initialization. | +| [AppCheckToken](./app-check.appchecktoken.md#appchecktoken_interface) | The token returned from an App Check provider. | +| [AppCheckTokenResult](./app-check.appchecktokenresult.md#appchecktokenresult_interface) | Result returned by getToken(). | +| [CustomProviderOptions](./app-check.customprovideroptions.md#customprovideroptions_interface) | Options when creating a [CustomProvider](./app-check.customprovider.md#customprovider_class). | + +## Type Aliases + +| Type Alias | Description | +| --- | --- | +| [AppCheckTokenListener](./app-check.md#appchecktokenlistener) | A listener that is called whenever the App Check token changes. | + +## initializeAppCheck() + +Activate App Check for the given app. Can be called only once per app. + +Signature: + +```typescript +export declare function initializeAppCheck(app: FirebaseApp | undefined, options: AppCheckOptions): AppCheck; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) \| undefined | the [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to activate App Check for | +| options | [AppCheckOptions](./app-check.appcheckoptions.md#appcheckoptions_interface) | App Check initialization options | + +Returns: + +[AppCheck](./app-check.appcheck.md#appcheck_interface) + +## getToken() + +Get the current App Check token. Attaches to the most recent in-flight request if one is present. Returns null if no token is present and no token requests are in-flight. + +Signature: + +```typescript +export declare function getToken(appCheckInstance: AppCheck, forceRefresh?: boolean): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| appCheckInstance | [AppCheck](./app-check.appcheck.md#appcheck_interface) | The App Check service instance. | +| forceRefresh | boolean | If true, will always try to fetch a fresh token. If false, will use a cached token if found in storage. | + +Returns: + +Promise<[AppCheckTokenResult](./app-check.appchecktokenresult.md#appchecktokenresult_interface)> + +## onTokenChanged() + +Registers a listener to changes in the token state. There can be more than one listener registered at the same time for one or more App Check instances. The listeners call back on the UI thread whenever the current token associated with this App Check instance changes. + +Signature: + +```typescript +export declare function onTokenChanged(appCheckInstance: AppCheck, observer: PartialObserver): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| appCheckInstance | [AppCheck](./app-check.appcheck.md#appcheck_interface) | The App Check service instance. | +| observer | [PartialObserver](./util.md#partialobserver)<[AppCheckTokenResult](./app-check.appchecktokenresult.md#appchecktokenresult_interface)> | An object with next, error, and complete properties. next is called with an [AppCheckTokenResult](./app-check.appchecktokenresult.md#appchecktokenresult_interface) whenever the token changes. error is optional and is called if an error is thrown by the listener (the next function). complete is unused, as the token stream is unending. | + +Returns: + +[Unsubscribe](./util.md#unsubscribe) + +A function that unsubscribes this listener. + +## onTokenChanged() + +Registers a listener to changes in the token state. There can be more than one listener registered at the same time for one or more App Check instances. The listeners call back on the UI thread whenever the current token associated with this App Check instance changes. + +Signature: + +```typescript +export declare function onTokenChanged(appCheckInstance: AppCheck, onNext: (tokenResult: AppCheckTokenResult) => void, onError?: (error: Error) => void, onCompletion?: () => void): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| appCheckInstance | [AppCheck](./app-check.appcheck.md#appcheck_interface) | The App Check service instance. | +| onNext | (tokenResult: [AppCheckTokenResult](./app-check.appchecktokenresult.md#appchecktokenresult_interface)) => void | When the token changes, this function is called with aa [AppCheckTokenResult](./app-check.appchecktokenresult.md#appchecktokenresult_interface). | +| onError | (error: Error) => void | Optional. Called if there is an error thrown by the listener (the onNext function). | +| onCompletion | () => void | Currently unused, as the token stream is unending. | + +Returns: + +[Unsubscribe](./util.md#unsubscribe) + +A function that unsubscribes this listener. + +## setTokenAutoRefreshEnabled() + +Set whether App Check will automatically refresh tokens as needed. + +Signature: + +```typescript +export declare function setTokenAutoRefreshEnabled(appCheckInstance: AppCheck, isTokenAutoRefreshEnabled: boolean): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| appCheckInstance | [AppCheck](./app-check.appcheck.md#appcheck_interface) | The App Check service instance. | +| isTokenAutoRefreshEnabled | boolean | If true, the SDK automatically refreshes App Check tokens as needed. This overrides any value set during initializeAppCheck(). | + +Returns: + +void + +## AppCheckTokenListener + +A listener that is called whenever the App Check token changes. + +Signature: + +```typescript +export declare type AppCheckTokenListener = (token: AppCheckTokenResult) => void; +``` diff --git a/docs-devsite/app-check.recaptchaenterpriseprovider.md b/docs-devsite/app-check.recaptchaenterpriseprovider.md new file mode 100644 index 00000000000..21222c24fb9 --- /dev/null +++ b/docs-devsite/app-check.recaptchaenterpriseprovider.md @@ -0,0 +1,43 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ReCaptchaEnterpriseProvider class +App Check provider that can obtain a reCAPTCHA Enterprise token and exchange it for an App Check token. + +Signature: + +```typescript +export declare class ReCaptchaEnterpriseProvider implements AppCheckProvider +``` +Implements: AppCheckProvider + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(\_siteKey)](./app-check.recaptchaenterpriseprovider.md#recaptchaenterpriseproviderconstructor) | | Create a ReCaptchaEnterpriseProvider instance. | + +## ReCaptchaEnterpriseProvider.(constructor) + +Create a ReCaptchaEnterpriseProvider instance. + +Signature: + +```typescript +constructor(_siteKey: string); +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| \_siteKey | string | | + diff --git a/docs-devsite/app-check.recaptchav3provider.md b/docs-devsite/app-check.recaptchav3provider.md new file mode 100644 index 00000000000..f2df61a639d --- /dev/null +++ b/docs-devsite/app-check.recaptchav3provider.md @@ -0,0 +1,43 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ReCaptchaV3Provider class +App Check provider that can obtain a reCAPTCHA V3 token and exchange it for an App Check token. + +Signature: + +```typescript +export declare class ReCaptchaV3Provider implements AppCheckProvider +``` +Implements: AppCheckProvider + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(\_siteKey)](./app-check.recaptchav3provider.md#recaptchav3providerconstructor) | | Create a ReCaptchaV3Provider instance. | + +## ReCaptchaV3Provider.(constructor) + +Create a ReCaptchaV3Provider instance. + +Signature: + +```typescript +constructor(_siteKey: string); +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| \_siteKey | string | | + diff --git a/docs-devsite/app.firebaseapp.md b/docs-devsite/app.firebaseapp.md new file mode 100644 index 00000000000..cafbfdd7c54 --- /dev/null +++ b/docs-devsite/app.firebaseapp.md @@ -0,0 +1,91 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FirebaseApp interface +A [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) holds the initialization information for a collection of services. + +Do not call this constructor directly. Instead, use [initializeApp()](./app.md#initializeapp) to create an app. + +Signature: + +```typescript +export interface FirebaseApp +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [automaticDataCollectionEnabled](./app.firebaseapp.md#firebaseappautomaticdatacollectionenabled) | boolean | The settable config flag for GDPR opt-in/opt-out | +| [name](./app.firebaseapp.md#firebaseappname) | string | The (read-only) name for this app.The default app's name is "[DEFAULT]". | +| [options](./app.firebaseapp.md#firebaseappoptions) | [FirebaseOptions](./app.firebaseoptions.md#firebaseoptions_interface) | The (read-only) configuration options for this app. These are the original parameters given in [initializeApp()](./app.md#initializeapp). | + +## FirebaseApp.automaticDataCollectionEnabled + +The settable config flag for GDPR opt-in/opt-out + +Signature: + +```typescript +automaticDataCollectionEnabled: boolean; +``` + +## FirebaseApp.name + +The (read-only) name for this app. + +The default app's name is `"[DEFAULT]"`. + +Signature: + +```typescript +readonly name: string; +``` + +### Example 1 + + +```javascript +// The default app's name is "[DEFAULT]" +const app = initializeApp(defaultAppConfig); +console.log(app.name); // "[DEFAULT]" + +``` + +### Example 2 + + +```javascript +// A named app's name is what you provide to initializeApp() +const otherApp = initializeApp(otherAppConfig, "other"); +console.log(otherApp.name); // "other" + +``` + +## FirebaseApp.options + +The (read-only) configuration options for this app. These are the original parameters given in [initializeApp()](./app.md#initializeapp). + +Signature: + +```typescript +readonly options: FirebaseOptions; +``` + +### Example + + +```javascript +const app = initializeApp(config); +console.log(app.options.databaseURL === config.databaseURL); // true + +``` + diff --git a/docs-devsite/app.firebaseappsettings.md b/docs-devsite/app.firebaseappsettings.md new file mode 100644 index 00000000000..3d9f858e548 --- /dev/null +++ b/docs-devsite/app.firebaseappsettings.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FirebaseAppSettings interface +Configuration options given to [initializeApp()](./app.md#initializeapp) + +Signature: + +```typescript +export interface FirebaseAppSettings +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [automaticDataCollectionEnabled](./app.firebaseappsettings.md#firebaseappsettingsautomaticdatacollectionenabled) | boolean | The settable config flag for GDPR opt-in/opt-out | +| [name](./app.firebaseappsettings.md#firebaseappsettingsname) | string | custom name for the Firebase App. The default value is "[DEFAULT]". | + +## FirebaseAppSettings.automaticDataCollectionEnabled + +The settable config flag for GDPR opt-in/opt-out + +Signature: + +```typescript +automaticDataCollectionEnabled?: boolean; +``` + +## FirebaseAppSettings.name + +custom name for the Firebase App. The default value is `"[DEFAULT]"`. + +Signature: + +```typescript +name?: string; +``` diff --git a/docs-devsite/app.firebaseoptions.md b/docs-devsite/app.firebaseoptions.md new file mode 100644 index 00000000000..5061c901676 --- /dev/null +++ b/docs-devsite/app.firebaseoptions.md @@ -0,0 +1,112 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FirebaseOptions interface +Firebase configuration object. Contains a set of parameters required by services in order to successfully communicate with Firebase server APIs and to associate client data with your Firebase project and Firebase application. Typically this object is populated by the Firebase console at project setup. See also: [Learn about the Firebase config object](https://firebase.google.com/docs/web/setup#config-object). + +Signature: + +```typescript +export interface FirebaseOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [apiKey](./app.firebaseoptions.md#firebaseoptionsapikey) | string | An encrypted string used when calling certain APIs that don't need to access private user data (example value: AIzaSyDOCAbC123dEf456GhI789jKl012-MnO). | +| [appId](./app.firebaseoptions.md#firebaseoptionsappid) | string | Unique identifier for the app. | +| [authDomain](./app.firebaseoptions.md#firebaseoptionsauthdomain) | string | Auth domain for the project ID. | +| [databaseURL](./app.firebaseoptions.md#firebaseoptionsdatabaseurl) | string | Default Realtime Database URL. | +| [measurementId](./app.firebaseoptions.md#firebaseoptionsmeasurementid) | string | An ID automatically created when you enable Analytics in your Firebase project and register a web app. In versions 7.20.0 and higher, this parameter is optional. | +| [messagingSenderId](./app.firebaseoptions.md#firebaseoptionsmessagingsenderid) | string | Unique numerical value used to identify each sender that can send Firebase Cloud Messaging messages to client apps. | +| [projectId](./app.firebaseoptions.md#firebaseoptionsprojectid) | string | The unique identifier for the project across all of Firebase and Google Cloud. | +| [storageBucket](./app.firebaseoptions.md#firebaseoptionsstoragebucket) | string | The default Cloud Storage bucket name. | + +## FirebaseOptions.apiKey + +An encrypted string used when calling certain APIs that don't need to access private user data (example value: `AIzaSyDOCAbC123dEf456GhI789jKl012-MnO`). + +Signature: + +```typescript +apiKey?: string; +``` + +## FirebaseOptions.appId + +Unique identifier for the app. + +Signature: + +```typescript +appId?: string; +``` + +## FirebaseOptions.authDomain + +Auth domain for the project ID. + +Signature: + +```typescript +authDomain?: string; +``` + +## FirebaseOptions.databaseURL + +Default Realtime Database URL. + +Signature: + +```typescript +databaseURL?: string; +``` + +## FirebaseOptions.measurementId + +An ID automatically created when you enable Analytics in your Firebase project and register a web app. In versions 7.20.0 and higher, this parameter is optional. + +Signature: + +```typescript +measurementId?: string; +``` + +## FirebaseOptions.messagingSenderId + +Unique numerical value used to identify each sender that can send Firebase Cloud Messaging messages to client apps. + +Signature: + +```typescript +messagingSenderId?: string; +``` + +## FirebaseOptions.projectId + +The unique identifier for the project across all of Firebase and Google Cloud. + +Signature: + +```typescript +projectId?: string; +``` + +## FirebaseOptions.storageBucket + +The default Cloud Storage bucket name. + +Signature: + +```typescript +storageBucket?: string; +``` diff --git a/docs-devsite/app.md b/docs-devsite/app.md new file mode 100644 index 00000000000..babb7d7bd2b --- /dev/null +++ b/docs-devsite/app.md @@ -0,0 +1,306 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# app package +Firebase App + +This package coordinates the communication between the different Firebase components + +## Functions + +| Function | Description | +| --- | --- | +| function(app...) | +| [deleteApp(app)](./app.md#deleteapp) | Renders this app unusable and frees the resources of all associated services. | +| function() | +| [getApps()](./app.md#getapps) | A (read-only) array of all initialized apps. | +| [initializeApp()](./app.md#initializeapp) | Creates and initializes a FirebaseApp instance. | +| function(libraryKeyOrName...) | +| [registerVersion(libraryKeyOrName, version, variant)](./app.md#registerversion) | Registers a library's name and version for platform logging purposes. | +| function(logCallback...) | +| [onLog(logCallback, options)](./app.md#onlog) | Sets log handler for all Firebase SDKs. | +| function(logLevel...) | +| [setLogLevel(logLevel)](./app.md#setloglevel) | Sets log level for all Firebase SDKs.All of the log types above the current log level are captured (i.e. if you set the log level to info, errors are logged, but debug and verbose logs are not). | +| function(name...) | +| [getApp(name)](./app.md#getapp) | Retrieves a [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance.When called with no arguments, the default app is returned. When an app name is provided, the app corresponding to that name is returned.An exception is thrown if the app being retrieved has not yet been initialized. | +| function(options...) | +| [initializeApp(options, name)](./app.md#initializeapp) | Creates and initializes a [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance.See [Add Firebase to your app](https://firebase.google.com/docs/web/setup#add_firebase_to_your_app) and [Initialize multiple projects](https://firebase.google.com/docs/web/setup#multiple-projects) for detailed documentation. | +| [initializeApp(options, config)](./app.md#initializeapp) | Creates and initializes a FirebaseApp instance. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | A [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) holds the initialization information for a collection of services.Do not call this constructor directly. Instead, use [initializeApp()](./app.md#initializeapp) to create an app. | +| [FirebaseAppSettings](./app.firebaseappsettings.md#firebaseappsettings_interface) | Configuration options given to [initializeApp()](./app.md#initializeapp) | +| [FirebaseOptions](./app.firebaseoptions.md#firebaseoptions_interface) | Firebase configuration object. Contains a set of parameters required by services in order to successfully communicate with Firebase server APIs and to associate client data with your Firebase project and Firebase application. Typically this object is populated by the Firebase console at project setup. See also: [Learn about the Firebase config object](https://firebase.google.com/docs/web/setup#config-object). | + +## Variables + +| Variable | Description | +| --- | --- | +| [SDK\_VERSION](./app.md#sdk_version) | The current SDK version. | + +## deleteApp() + +Renders this app unusable and frees the resources of all associated services. + +Signature: + +```typescript +export declare function deleteApp(app: FirebaseApp): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | | + +Returns: + +Promise<void> + +### Example + + +```javascript +deleteApp(app) + .then(function() { + console.log("App deleted successfully"); + }) + .catch(function(error) { + console.log("Error deleting app:", error); + }); + +``` + +## getApps() + +A (read-only) array of all initialized apps. + +Signature: + +```typescript +export declare function getApps(): FirebaseApp[]; +``` +Returns: + +[FirebaseApp](./app.firebaseapp.md#firebaseapp_interface)\[\] + +## initializeApp() + +Creates and initializes a FirebaseApp instance. + +Signature: + +```typescript +export declare function initializeApp(): FirebaseApp; +``` +Returns: + +[FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) + +## registerVersion() + +Registers a library's name and version for platform logging purposes. + +Signature: + +```typescript +export declare function registerVersion(libraryKeyOrName: string, version: string, variant?: string): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| libraryKeyOrName | string | | +| version | string | Current version of that library. | +| variant | string | Bundle variant, e.g., node, rn, etc. | + +Returns: + +void + +## onLog() + +Sets log handler for all Firebase SDKs. + +Signature: + +```typescript +export declare function onLog(logCallback: LogCallback | null, options?: LogOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| logCallback | LogCallback \| null | An optional custom log handler that executes user code whenever the Firebase SDK makes a logging call. | +| options | LogOptions | | + +Returns: + +void + +## setLogLevel() + +Sets log level for all Firebase SDKs. + +All of the log types above the current log level are captured (i.e. if you set the log level to `info`, errors are logged, but `debug` and `verbose` logs are not). + +Signature: + +```typescript +export declare function setLogLevel(logLevel: LogLevelString): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| logLevel | LogLevelString | | + +Returns: + +void + +## getApp() + +Retrieves a [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. + +When called with no arguments, the default app is returned. When an app name is provided, the app corresponding to that name is returned. + +An exception is thrown if the app being retrieved has not yet been initialized. + +Signature: + +```typescript +export declare function getApp(name?: string): FirebaseApp; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| name | string | Optional name of the app to return. If no name is provided, the default is "[DEFAULT]". | + +Returns: + +[FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) + +The app corresponding to the provided app name. If no app name is provided, the default app is returned. + +### Example 1 + + +```javascript +// Return the default app +const app = getApp(); + +``` + +### Example 2 + + +```javascript +// Return a named app +const otherApp = getApp("otherApp"); + +``` + +## initializeApp() + +Creates and initializes a [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. + +See [Add Firebase to your app](https://firebase.google.com/docs/web/setup#add_firebase_to_your_app) and [Initialize multiple projects](https://firebase.google.com/docs/web/setup#multiple-projects) for detailed documentation. + +Signature: + +```typescript +export declare function initializeApp(options: FirebaseOptions, name?: string): FirebaseApp; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| options | [FirebaseOptions](./app.firebaseoptions.md#firebaseoptions_interface) | Options to configure the app's services. | +| name | string | Optional name of the app to initialize. If no name is provided, the default is "[DEFAULT]". | + +Returns: + +[FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) + +The initialized app. + +### Example 1 + + +```javascript + +// Initialize default app +// Retrieve your own options values by adding a web app on +// https://console.firebase.google.com +initializeApp({ + apiKey: "AIza....", // Auth / General Use + authDomain: "YOUR_APP.firebaseapp.com", // Auth with popup/redirect + databaseURL: "https://YOUR_APP.firebaseio.com", // Realtime Database + storageBucket: "YOUR_APP.appspot.com", // Storage + messagingSenderId: "123456789" // Cloud Messaging +}); + +``` + +### Example 2 + + +```javascript + +// Initialize another app +const otherApp = initializeApp({ + databaseURL: "https://.firebaseio.com", + storageBucket: ".appspot.com" +}, "otherApp"); + +``` + +## initializeApp() + +Creates and initializes a FirebaseApp instance. + +Signature: + +```typescript +export declare function initializeApp(options: FirebaseOptions, config?: FirebaseAppSettings): FirebaseApp; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| options | [FirebaseOptions](./app.firebaseoptions.md#firebaseoptions_interface) | Options to configure the app's services. | +| config | [FirebaseAppSettings](./app.firebaseappsettings.md#firebaseappsettings_interface) | FirebaseApp Configuration | + +Returns: + +[FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) + +## SDK\_VERSION + +The current SDK version. + +Signature: + +```typescript +SDK_VERSION: string +``` diff --git a/docs-devsite/auth.actioncodeinfo.md b/docs-devsite/auth.actioncodeinfo.md new file mode 100644 index 00000000000..980acf6d967 --- /dev/null +++ b/docs-devsite/auth.actioncodeinfo.md @@ -0,0 +1,58 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ActionCodeInfo interface +A response from [checkActionCode()](./auth.md#checkactioncode). + +Signature: + +```typescript +export interface ActionCodeInfo +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [data](./auth.actioncodeinfo.md#actioncodeinfodata) | { email?: string \| null; multiFactorInfo?: [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) \| null; previousEmail?: string \| null; } | The data associated with the action code. | +| [operation](./auth.actioncodeinfo.md#actioncodeinfooperation) | typeof [ActionCodeOperationMap](./auth.md#actioncodeoperation)\[keyof typeof [ActionCodeOperationMap](./auth.md#actioncodeoperation)\] | The type of operation that generated the action code. | + +## ActionCodeInfo.data + +The data associated with the action code. + +For the [ActionCodeOperation](./auth.md#actioncodeoperation).PASSWORD\_RESET, [ActionCodeOperation](./auth.md#actioncodeoperation).VERIFY\_EMAIL, and [ActionCodeOperation](./auth.md#actioncodeoperation).RECOVER\_EMAIL actions, this object contains an email field with the address the email was sent to. + +For the [ActionCodeOperation](./auth.md#actioncodeoperation).RECOVER\_EMAIL action, which allows a user to undo an email address change, this object also contains a `previousEmail` field with the user account's current email address. After the action completes, the user's email address will revert to the value in the `email` field from the value in `previousEmail` field. + +For the [ActionCodeOperation](./auth.md#actioncodeoperation).VERIFY\_AND\_CHANGE\_EMAIL action, which allows a user to verify the email before updating it, this object contains a `previousEmail` field with the user account's email address before updating. After the action completes, the user's email address will be updated to the value in the `email` field from the value in `previousEmail` field. + +For the [ActionCodeOperation](./auth.md#actioncodeoperation).REVERT\_SECOND\_FACTOR\_ADDITION action, which allows a user to unenroll a newly added second factor, this object contains a `multiFactorInfo` field with the information about the second factor. For phone second factor, the `multiFactorInfo` is a [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) object, which contains the phone number. + +Signature: + +```typescript +data: { + email?: string | null; + multiFactorInfo?: MultiFactorInfo | null; + previousEmail?: string | null; + }; +``` + +## ActionCodeInfo.operation + +The type of operation that generated the action code. + +Signature: + +```typescript +operation: typeof ActionCodeOperationMap[keyof typeof ActionCodeOperationMap]; +``` diff --git a/docs-devsite/auth.actioncodesettings.md b/docs-devsite/auth.actioncodesettings.md new file mode 100644 index 00000000000..a12144adaf4 --- /dev/null +++ b/docs-devsite/auth.actioncodesettings.md @@ -0,0 +1,95 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ActionCodeSettings interface +An interface that defines the required continue/state URL with optional Android and iOS bundle identifiers. + +Signature: + +```typescript +export interface ActionCodeSettings +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [android](./auth.actioncodesettings.md#actioncodesettingsandroid) | { installApp?: boolean; minimumVersion?: string; packageName: string; } | Sets the Android package name. | +| [dynamicLinkDomain](./auth.actioncodesettings.md#actioncodesettingsdynamiclinkdomain) | string | When multiple custom dynamic link domains are defined for a project, specify which one to use when the link is to be opened via a specified mobile app (for example, example.page.link). | +| [handleCodeInApp](./auth.actioncodesettings.md#actioncodesettingshandlecodeinapp) | boolean | When set to true, the action code link will be be sent as a Universal Link or Android App Link and will be opened by the app if installed. | +| [iOS](./auth.actioncodesettings.md#actioncodesettingsios) | { bundleId: string; } | Sets the iOS bundle ID. | +| [url](./auth.actioncodesettings.md#actioncodesettingsurl) | string | Sets the link continue/state URL. | + +## ActionCodeSettings.android + +Sets the Android package name. + +This will try to open the link in an android app if it is installed. If `installApp` is passed, it specifies whether to install the Android app if the device supports it and the app is not already installed. If this field is provided without a `packageName`, an error is thrown explaining that the `packageName` must be provided in conjunction with this field. If `minimumVersion` is specified, and an older version of the app is installed, the user is taken to the Play Store to upgrade the app. + +Signature: + +```typescript +android?: { + installApp?: boolean; + minimumVersion?: string; + packageName: string; + }; +``` + +## ActionCodeSettings.dynamicLinkDomain + +When multiple custom dynamic link domains are defined for a project, specify which one to use when the link is to be opened via a specified mobile app (for example, `example.page.link`). + +Signature: + +```typescript +dynamicLinkDomain?: string; +``` + +## ActionCodeSettings.handleCodeInApp + +When set to true, the action code link will be be sent as a Universal Link or Android App Link and will be opened by the app if installed. + +In the false case, the code will be sent to the web widget first and then on continue will redirect to the app if installed. + +Signature: + +```typescript +handleCodeInApp?: boolean; +``` + +## ActionCodeSettings.iOS + +Sets the iOS bundle ID. + +This will try to open the link in an iOS app if it is installed. + +App installation is not supported for iOS. + +Signature: + +```typescript +iOS?: { + bundleId: string; + }; +``` + +## ActionCodeSettings.url + +Sets the link continue/state URL. + +This has different meanings in different contexts: - When the link is handled in the web action widgets, this is the deep link in the `continueUrl` query parameter. - When the link is handled in the app directly, this is the `continueUrl` query parameter in the deep link of the Dynamic Link. + +Signature: + +```typescript +url: string; +``` diff --git a/docs-devsite/auth.actioncodeurl.md b/docs-devsite/auth.actioncodeurl.md new file mode 100644 index 00000000000..f59e20d8c15 --- /dev/null +++ b/docs-devsite/auth.actioncodeurl.md @@ -0,0 +1,121 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ActionCodeURL class +A utility class to parse email action URLs such as password reset, email verification, email link sign in, etc. + +The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `ActionCodeURL` class. + +Signature: + +```typescript +export declare class ActionCodeURL +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [apiKey](./auth.actioncodeurl.md#actioncodeurlapikey) | | string | The API key of the email action link. | +| [code](./auth.actioncodeurl.md#actioncodeurlcode) | | string | The action code of the email action link. | +| [continueUrl](./auth.actioncodeurl.md#actioncodeurlcontinueurl) | | string \| null | The continue URL of the email action link. Null if not provided. | +| [languageCode](./auth.actioncodeurl.md#actioncodeurllanguagecode) | | string \| null | The language code of the email action link. Null if not provided. | +| [operation](./auth.actioncodeurl.md#actioncodeurloperation) | | string | The action performed by the email action link. It returns from one of the types from [ActionCodeInfo](./auth.actioncodeinfo.md#actioncodeinfo_interface) | +| [tenantId](./auth.actioncodeurl.md#actioncodeurltenantid) | | string \| null | The tenant ID of the email action link. Null if the email action is from the parent project. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [parseLink(link)](./auth.actioncodeurl.md#actioncodeurlparselink) | static | Parses the email action link string and returns an [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) if the link is valid, otherwise returns null. | + +## ActionCodeURL.apiKey + +The API key of the email action link. + +Signature: + +```typescript +readonly apiKey: string; +``` + +## ActionCodeURL.code + +The action code of the email action link. + +Signature: + +```typescript +readonly code: string; +``` + +## ActionCodeURL.continueUrl + +The continue URL of the email action link. Null if not provided. + +Signature: + +```typescript +readonly continueUrl: string | null; +``` + +## ActionCodeURL.languageCode + +The language code of the email action link. Null if not provided. + +Signature: + +```typescript +readonly languageCode: string | null; +``` + +## ActionCodeURL.operation + +The action performed by the email action link. It returns from one of the types from [ActionCodeInfo](./auth.actioncodeinfo.md#actioncodeinfo_interface) + +Signature: + +```typescript +readonly operation: string; +``` + +## ActionCodeURL.tenantId + +The tenant ID of the email action link. Null if the email action is from the parent project. + +Signature: + +```typescript +readonly tenantId: string | null; +``` + +## ActionCodeURL.parseLink() + +Parses the email action link string and returns an [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) if the link is valid, otherwise returns null. + +Signature: + +```typescript +static parseLink(link: string): ActionCodeURL | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| link | string | The email action link string. | + +Returns: + +[ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) \| null + +The [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) object, or null if the link is invalid. + diff --git a/docs-devsite/auth.additionaluserinfo.md b/docs-devsite/auth.additionaluserinfo.md new file mode 100644 index 00000000000..ec6ca5740ac --- /dev/null +++ b/docs-devsite/auth.additionaluserinfo.md @@ -0,0 +1,68 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AdditionalUserInfo interface +A structure containing additional user information from a federated identity provider. + +Signature: + +```typescript +export interface AdditionalUserInfo +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [isNewUser](./auth.additionaluserinfo.md#additionaluserinfoisnewuser) | boolean | Whether the user is new (created via sign-up) or existing (authenticated using sign-in). | +| [profile](./auth.additionaluserinfo.md#additionaluserinfoprofile) | Record<string, unknown> \| null | Map containing IDP-specific user data. | +| [providerId](./auth.additionaluserinfo.md#additionaluserinfoproviderid) | string \| null | Identifier for the provider used to authenticate this user. | +| [username](./auth.additionaluserinfo.md#additionaluserinfousername) | string \| null | The username if the provider is GitHub or Twitter. | + +## AdditionalUserInfo.isNewUser + +Whether the user is new (created via sign-up) or existing (authenticated using sign-in). + +Signature: + +```typescript +readonly isNewUser: boolean; +``` + +## AdditionalUserInfo.profile + +Map containing IDP-specific user data. + +Signature: + +```typescript +readonly profile: Record | null; +``` + +## AdditionalUserInfo.providerId + +Identifier for the provider used to authenticate this user. + +Signature: + +```typescript +readonly providerId: string | null; +``` + +## AdditionalUserInfo.username + +The username if the provider is GitHub or Twitter. + +Signature: + +```typescript +readonly username?: string | null; +``` diff --git a/docs-devsite/auth.applicationverifier.md b/docs-devsite/auth.applicationverifier.md new file mode 100644 index 00000000000..08e81aa3362 --- /dev/null +++ b/docs-devsite/auth.applicationverifier.md @@ -0,0 +1,59 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ApplicationVerifier interface +A verifier for domain verification and abuse prevention. + +Currently, the only implementation is [RecaptchaVerifier](./auth.recaptchaverifier.md#recaptchaverifier_class). + +Signature: + +```typescript +export interface ApplicationVerifier +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [type](./auth.applicationverifier.md#applicationverifiertype) | string | Identifies the type of application verifier (e.g. "recaptcha"). | + +## Methods + +| Method | Description | +| --- | --- | +| [verify()](./auth.applicationverifier.md#applicationverifierverify) | Executes the verification process. | + +## ApplicationVerifier.type + +Identifies the type of application verifier (e.g. "recaptcha"). + +Signature: + +```typescript +readonly type: string; +``` + +## ApplicationVerifier.verify() + +Executes the verification process. + +Signature: + +```typescript +verify(): Promise; +``` +Returns: + +Promise<string> + +A Promise for a token that can be used to assert the validity of a request. + diff --git a/docs-devsite/auth.auth.md b/docs-devsite/auth.auth.md new file mode 100644 index 00000000000..9bd59ba6c56 --- /dev/null +++ b/docs-devsite/auth.auth.md @@ -0,0 +1,299 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Auth interface +Interface representing Firebase Auth service. + +See [Firebase Authentication](https://firebase.google.com/docs/auth/) for a full guide on how to use the Firebase Auth service. + +Signature: + +```typescript +export interface Auth +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [app](./auth.auth.md#authapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with the Auth service instance. | +| [config](./auth.auth.md#authconfig) | [Config](./auth.config.md#config_interface) | The [Config](./auth.config.md#config_interface) used to initialize this instance. | +| [currentUser](./auth.auth.md#authcurrentuser) | [User](./auth.user.md#user_interface) \| null | The currently signed-in user (or null). | +| [emulatorConfig](./auth.auth.md#authemulatorconfig) | [EmulatorConfig](./auth.emulatorconfig.md#emulatorconfig_interface) \| null | The current emulator configuration (or null). | +| [languageCode](./auth.auth.md#authlanguagecode) | string \| null | The [Auth](./auth.auth.md#auth_interface) instance's language code. | +| [name](./auth.auth.md#authname) | string | The name of the app associated with the Auth service instance. | +| [settings](./auth.auth.md#authsettings) | [AuthSettings](./auth.authsettings.md#authsettings_interface) | The [Auth](./auth.auth.md#auth_interface) instance's settings. | +| [tenantId](./auth.auth.md#authtenantid) | string \| null | The [Auth](./auth.auth.md#auth_interface) instance's tenant ID. | + +## Methods + +| Method | Description | +| --- | --- | +| [beforeAuthStateChanged(callback, onAbort)](./auth.auth.md#authbeforeauthstatechanged) | Adds a blocking callback that runs before an auth state change sets a new user. | +| [onAuthStateChanged(nextOrObserver, error, completed)](./auth.auth.md#authonauthstatechanged) | Adds an observer for changes to the user's sign-in state. | +| [onIdTokenChanged(nextOrObserver, error, completed)](./auth.auth.md#authonidtokenchanged) | Adds an observer for changes to the signed-in user's ID token. | +| [setPersistence(persistence)](./auth.auth.md#authsetpersistence) | Changes the type of persistence on the Auth instance. | +| [signOut()](./auth.auth.md#authsignout) | Signs out the current user. | +| [updateCurrentUser(user)](./auth.auth.md#authupdatecurrentuser) | Asynchronously sets the provided user as [Auth.currentUser](./auth.auth.md#authcurrentuser) on the [Auth](./auth.auth.md#auth_interface) instance. | +| [useDeviceLanguage()](./auth.auth.md#authusedevicelanguage) | Sets the current language to the default device/browser preference. | + +## Auth.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with the `Auth` service instance. + +Signature: + +```typescript +readonly app: FirebaseApp; +``` + +## Auth.config + +The [Config](./auth.config.md#config_interface) used to initialize this instance. + +Signature: + +```typescript +readonly config: Config; +``` + +## Auth.currentUser + +The currently signed-in user (or null). + +Signature: + +```typescript +readonly currentUser: User | null; +``` + +## Auth.emulatorConfig + +The current emulator configuration (or null). + +Signature: + +```typescript +readonly emulatorConfig: EmulatorConfig | null; +``` + +## Auth.languageCode + +The [Auth](./auth.auth.md#auth_interface) instance's language code. + +This is a readable/writable property. When set to null, the default Firebase Console language setting is applied. The language code will propagate to email action templates (password reset, email verification and email change revocation), SMS templates for phone authentication, reCAPTCHA verifier and OAuth popup/redirect operations provided the specified providers support localization with the language code specified. + +Signature: + +```typescript +languageCode: string | null; +``` + +## Auth.name + +The name of the app associated with the `Auth` service instance. + +Signature: + +```typescript +readonly name: string; +``` + +## Auth.settings + +The [Auth](./auth.auth.md#auth_interface) instance's settings. + +This is used to edit/read configuration related options such as app verification mode for phone authentication. + +Signature: + +```typescript +readonly settings: AuthSettings; +``` + +## Auth.tenantId + +The [Auth](./auth.auth.md#auth_interface) instance's tenant ID. + +This is a readable/writable property. When you set the tenant ID of an [Auth](./auth.auth.md#auth_interface) instance, all future sign-in/sign-up operations will pass this tenant ID and sign in or sign up users to the specified tenant project. When set to null, users are signed in to the parent project. + +Signature: + +```typescript +tenantId: string | null; +``` + +### Example + + +```javascript +// Set the tenant ID on Auth instance. +auth.tenantId = 'TENANT_PROJECT_ID'; + +// All future sign-in request now include tenant ID. +const result = await signInWithEmailAndPassword(auth, email, password); +// result.user.tenantId should be 'TENANT_PROJECT_ID'. + +``` + +## Auth.beforeAuthStateChanged() + +Adds a blocking callback that runs before an auth state change sets a new user. + +Signature: + +```typescript +beforeAuthStateChanged(callback: (user: User | null) => void | Promise, onAbort?: () => void): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| callback | (user: [User](./auth.user.md#user_interface) \| null) => void \| Promise<void> | callback triggered before new user value is set. If this throws, it blocks the user from being set. | +| onAbort | () => void | callback triggered if a later beforeAuthStateChanged() callback throws, allowing you to undo any side effects. | + +Returns: + +[Unsubscribe](./util.md#unsubscribe) + +## Auth.onAuthStateChanged() + +Adds an observer for changes to the user's sign-in state. + +To keep the old behavior, see [Auth.onIdTokenChanged()](./auth.auth.md#authonidtokenchanged). + +Signature: + +```typescript +onAuthStateChanged(nextOrObserver: NextOrObserver, error?: ErrorFn, completed?: CompleteFn): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| nextOrObserver | [NextOrObserver](./auth.md#nextorobserver)<[User](./auth.user.md#user_interface) \| null> | callback triggered on change. | +| error | [ErrorFn](./util.md#errorfn) | Deprecated. This callback is never triggered. Errors on signing in/out can be caught in promises returned from sign-in/sign-out functions. | +| completed | [CompleteFn](./util.md#completefn) | Deprecated. This callback is never triggered. | + +Returns: + +[Unsubscribe](./util.md#unsubscribe) + +## Auth.onIdTokenChanged() + +Adds an observer for changes to the signed-in user's ID token. + +This includes sign-in, sign-out, and token refresh events. + +Signature: + +```typescript +onIdTokenChanged(nextOrObserver: NextOrObserver, error?: ErrorFn, completed?: CompleteFn): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| nextOrObserver | [NextOrObserver](./auth.md#nextorobserver)<[User](./auth.user.md#user_interface) \| null> | callback triggered on change. | +| error | [ErrorFn](./util.md#errorfn) | Deprecated. This callback is never triggered. Errors on signing in/out can be caught in promises returned from sign-in/sign-out functions. | +| completed | [CompleteFn](./util.md#completefn) | Deprecated. This callback is never triggered. | + +Returns: + +[Unsubscribe](./util.md#unsubscribe) + +## Auth.setPersistence() + +Changes the type of persistence on the `Auth` instance. + +This will affect the currently saved Auth session and applies this type of persistence for future sign-in requests, including sign-in with redirect requests. + +This makes it easy for a user signing in to specify whether their session should be remembered or not. It also makes it easier to never persist the Auth state for applications that are shared by other users or have sensitive data. + +Signature: + +```typescript +setPersistence(persistence: Persistence): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| persistence | [Persistence](./auth.persistence.md#persistence_interface) | The [Persistence](./auth.persistence.md#persistence_interface) to use. | + +Returns: + +Promise<void> + +### Example + + +```javascript +auth.setPersistence(browserSessionPersistence); + +``` + +## Auth.signOut() + +Signs out the current user. + +Signature: + +```typescript +signOut(): Promise; +``` +Returns: + +Promise<void> + +## Auth.updateCurrentUser() + +Asynchronously sets the provided user as [Auth.currentUser](./auth.auth.md#authcurrentuser) on the [Auth](./auth.auth.md#auth_interface) instance. + +A new instance copy of the user provided will be made and set as currentUser. + +This will trigger [Auth.onAuthStateChanged()](./auth.auth.md#authonauthstatechanged) and [Auth.onIdTokenChanged()](./auth.auth.md#authonidtokenchanged) listeners like other sign in methods. + +The operation fails with an error if the user to be updated belongs to a different Firebase project. + +Signature: + +```typescript +updateCurrentUser(user: User | null): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) \| null | The new [User](./auth.user.md#user_interface). | + +Returns: + +Promise<void> + +## Auth.useDeviceLanguage() + +Sets the current language to the default device/browser preference. + +Signature: + +```typescript +useDeviceLanguage(): void; +``` +Returns: + +void + diff --git a/docs-devsite/auth.authcredential.md b/docs-devsite/auth.authcredential.md new file mode 100644 index 00000000000..fdc6fe392c4 --- /dev/null +++ b/docs-devsite/auth.authcredential.md @@ -0,0 +1,76 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AuthCredential class +Interface that represents the credentials returned by an [AuthProvider](./auth.authprovider.md#authprovider_interface). + +Implementations specify the details about each auth provider's credential requirements. + +The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `AuthCredential` class. + +Signature: + +```typescript +export declare class AuthCredential +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [providerId](./auth.authcredential.md#authcredentialproviderid) | | string | The authentication provider ID for the credential. | +| [signInMethod](./auth.authcredential.md#authcredentialsigninmethod) | | string | The authentication sign in method for the credential. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [toJSON()](./auth.authcredential.md#authcredentialtojson) | | Returns a JSON-serializable representation of this object. | + +## AuthCredential.providerId + +The authentication provider ID for the credential. + +For example, 'facebook.com', or 'google.com'. + +Signature: + +```typescript +readonly providerId: string; +``` + +## AuthCredential.signInMethod + +The authentication sign in method for the credential. + +For example, [SignInMethod](./auth.md#signinmethod).EMAIL\_PASSWORD, or [SignInMethod](./auth.md#signinmethod).EMAIL\_LINK. This corresponds to the sign-in method identifier as returned in [fetchSignInMethodsForEmail()](./auth.md#fetchsigninmethodsforemail). + +Signature: + +```typescript +readonly signInMethod: string; +``` + +## AuthCredential.toJSON() + +Returns a JSON-serializable representation of this object. + +Signature: + +```typescript +toJSON(): object; +``` +Returns: + +object + +a JSON-serializable representation of this object. + diff --git a/docs-devsite/auth.autherror.md b/docs-devsite/auth.autherror.md new file mode 100644 index 00000000000..f91b835b5ed --- /dev/null +++ b/docs-devsite/auth.autherror.md @@ -0,0 +1,41 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AuthError interface +Interface for an `Auth` error. + +Signature: + +```typescript +export interface AuthError extends FirebaseError +``` +Extends: [FirebaseError](./util.firebaseerror.md#firebaseerror_class) + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [customData](./auth.autherror.md#autherrorcustomdata) | { readonly appName: string; readonly email?: string; readonly phoneNumber?: string; readonly tenantId?: string; } | Details about the Firebase Auth error. | + +## AuthError.customData + +Details about the Firebase Auth error. + +Signature: + +```typescript +readonly customData: { + readonly appName: string; + readonly email?: string; + readonly phoneNumber?: string; + readonly tenantId?: string; + }; +``` diff --git a/docs-devsite/auth.autherrormap.md b/docs-devsite/auth.autherrormap.md new file mode 100644 index 00000000000..e0316a8ed59 --- /dev/null +++ b/docs-devsite/auth.autherrormap.md @@ -0,0 +1,27 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AuthErrorMap interface +A mapping of error codes to error messages. + +While error messages are useful for debugging (providing verbose textual context around what went wrong), these strings take up a lot of space in the compiled code. When deploying code in production, using [prodErrorMap](./auth.md#proderrormap) will save you roughly 10k compressed/gzipped over [debugErrorMap](./auth.md#debugerrormap). You can select the error map during initialization: + +```javascript +initializeAuth(app, {errorMap: debugErrorMap}) + +``` +When initializing Auth, [prodErrorMap](./auth.md#proderrormap) is default. + +Signature: + +```typescript +export interface AuthErrorMap +``` diff --git a/docs-devsite/auth.authprovider.md b/docs-devsite/auth.authprovider.md new file mode 100644 index 00000000000..a9871dad0a8 --- /dev/null +++ b/docs-devsite/auth.authprovider.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AuthProvider interface +Interface that represents an auth provider, used to facilitate creating [AuthCredential](./auth.authcredential.md#authcredential_class). + +Signature: + +```typescript +export interface AuthProvider +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [providerId](./auth.authprovider.md#authproviderproviderid) | string | Provider for which credentials can be constructed. | + +## AuthProvider.providerId + +Provider for which credentials can be constructed. + +Signature: + +```typescript +readonly providerId: string; +``` diff --git a/docs-devsite/auth.authsettings.md b/docs-devsite/auth.authsettings.md new file mode 100644 index 00000000000..c54fac47da4 --- /dev/null +++ b/docs-devsite/auth.authsettings.md @@ -0,0 +1,41 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AuthSettings interface +Interface representing an [Auth](./auth.auth.md#auth_interface) instance's settings. + +Currently used for enabling/disabling app verification for phone Auth testing. + +Signature: + +```typescript +export interface AuthSettings +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [appVerificationDisabledForTesting](./auth.authsettings.md#authsettingsappverificationdisabledfortesting) | boolean | When set, this property disables app verification for the purpose of testing phone authentication. For this property to take effect, it needs to be set before rendering a reCAPTCHA app verifier. When this is disabled, a mock reCAPTCHA is rendered instead. This is useful for manual testing during development or for automated integration tests.In order to use this feature, you will need to [whitelist your phone number](https://firebase.google.com/docs/auth/web/phone-auth#test-with-whitelisted-phone-numbers) via the Firebase Console.The default value is false (app verification is enabled). | + +## AuthSettings.appVerificationDisabledForTesting + +When set, this property disables app verification for the purpose of testing phone authentication. For this property to take effect, it needs to be set before rendering a reCAPTCHA app verifier. When this is disabled, a mock reCAPTCHA is rendered instead. This is useful for manual testing during development or for automated integration tests. + +In order to use this feature, you will need to [whitelist your phone number](https://firebase.google.com/docs/auth/web/phone-auth#test-with-whitelisted-phone-numbers) via the Firebase Console. + +The default value is false (app verification is enabled). + +Signature: + +```typescript +appVerificationDisabledForTesting: boolean; +``` diff --git a/docs-devsite/auth.config.md b/docs-devsite/auth.config.md new file mode 100644 index 00000000000..c22a3930f87 --- /dev/null +++ b/docs-devsite/auth.config.md @@ -0,0 +1,90 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Config interface +Interface representing the `Auth` config. + +Signature: + +```typescript +export interface Config +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [apiHost](./auth.config.md#configapihost) | string | The host at which the Firebase Auth backend is running. | +| [apiKey](./auth.config.md#configapikey) | string | The API Key used to communicate with the Firebase Auth backend. | +| [apiScheme](./auth.config.md#configapischeme) | string | The scheme used to communicate with the Firebase Auth backend. | +| [authDomain](./auth.config.md#configauthdomain) | string | The domain at which the web widgets are hosted (provided via Firebase Config). | +| [sdkClientVersion](./auth.config.md#configsdkclientversion) | string | The SDK Client Version. | +| [tokenApiHost](./auth.config.md#configtokenapihost) | string | The host at which the Secure Token API is running. | + +## Config.apiHost + +The host at which the Firebase Auth backend is running. + +Signature: + +```typescript +apiHost: string; +``` + +## Config.apiKey + +The API Key used to communicate with the Firebase Auth backend. + +Signature: + +```typescript +apiKey: string; +``` + +## Config.apiScheme + +The scheme used to communicate with the Firebase Auth backend. + +Signature: + +```typescript +apiScheme: string; +``` + +## Config.authDomain + +The domain at which the web widgets are hosted (provided via Firebase Config). + +Signature: + +```typescript +authDomain?: string; +``` + +## Config.sdkClientVersion + +The SDK Client Version. + +Signature: + +```typescript +sdkClientVersion: string; +``` + +## Config.tokenApiHost + +The host at which the Secure Token API is running. + +Signature: + +```typescript +tokenApiHost: string; +``` diff --git a/docs-devsite/auth.confirmationresult.md b/docs-devsite/auth.confirmationresult.md new file mode 100644 index 00000000000..5d6a209b12d --- /dev/null +++ b/docs-devsite/auth.confirmationresult.md @@ -0,0 +1,74 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ConfirmationResult interface +A result from a phone number sign-in, link, or reauthenticate call. + +Signature: + +```typescript +export interface ConfirmationResult +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [verificationId](./auth.confirmationresult.md#confirmationresultverificationid) | string | The phone number authentication operation's verification ID. | + +## Methods + +| Method | Description | +| --- | --- | +| [confirm(verificationCode)](./auth.confirmationresult.md#confirmationresultconfirm) | Finishes a phone number sign-in, link, or reauthentication. | + +## ConfirmationResult.verificationId + +The phone number authentication operation's verification ID. + +This can be used along with the verification code to initialize a [PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class). + +Signature: + +```typescript +readonly verificationId: string; +``` + +## ConfirmationResult.confirm() + +Finishes a phone number sign-in, link, or reauthentication. + +Signature: + +```typescript +confirm(verificationCode: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| verificationCode | string | The code that was sent to the user's mobile device. | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> + +### Example + + +```javascript +const confirmationResult = await signInWithPhoneNumber(auth, phoneNumber, applicationVerifier); +// Obtain verificationCode from the user. +const userCredential = await confirmationResult.confirm(verificationCode); + +``` + diff --git a/docs-devsite/auth.dependencies.md b/docs-devsite/auth.dependencies.md new file mode 100644 index 00000000000..9112f016fa1 --- /dev/null +++ b/docs-devsite/auth.dependencies.md @@ -0,0 +1,63 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Dependencies interface +The dependencies that can be used to initialize an [Auth](./auth.auth.md#auth_interface) instance. + +The modular SDK enables tree shaking by allowing explicit declarations of dependencies. For example, a web app does not need to include code that enables Cordova redirect sign in. That functionality is therefore split into [browserPopupRedirectResolver](./auth.md#browserpopupredirectresolver) and [cordovaPopupRedirectResolver](./auth.md#cordovapopupredirectresolver). The dependencies object is how Auth is configured to reduce bundle sizes. + +There are two ways to initialize an [Auth](./auth.auth.md#auth_interface) instance: [getAuth()](./auth.md#getauth) and [initializeAuth()](./auth.md#initializeauth). `getAuth` initializes everything using platform-specific configurations, while `initializeAuth` takes a `Dependencies` object directly, giving you more control over what is used. + +Signature: + +```typescript +export interface Dependencies +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [errorMap](./auth.dependencies.md#dependencieserrormap) | [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) | Which [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) to use. | +| [persistence](./auth.dependencies.md#dependenciespersistence) | [Persistence](./auth.persistence.md#persistence_interface) \| [Persistence](./auth.persistence.md#persistence_interface)\[\] | Which [Persistence](./auth.persistence.md#persistence_interface) to use. If this is an array, the first Persistence that the device supports is used. The SDK searches for an existing account in order and, if one is found in a secondary Persistence, the account is moved to the primary Persistence.If no persistence is provided, the SDK falls back on [inMemoryPersistence](./auth.md#inmemorypersistence). | +| [popupRedirectResolver](./auth.dependencies.md#dependenciespopupredirectresolver) | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | The [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) to use. This value depends on the platform. Options are [browserPopupRedirectResolver](./auth.md#browserpopupredirectresolver) and [cordovaPopupRedirectResolver](./auth.md#cordovapopupredirectresolver). This field is optional if neither [signInWithPopup()](./auth.md#signinwithpopup) or [signInWithRedirect()](./auth.md#signinwithredirect) are being used. | + +## Dependencies.errorMap + +Which [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) to use. + +Signature: + +```typescript +errorMap?: AuthErrorMap; +``` + +## Dependencies.persistence + +Which [Persistence](./auth.persistence.md#persistence_interface) to use. If this is an array, the first `Persistence` that the device supports is used. The SDK searches for an existing account in order and, if one is found in a secondary `Persistence`, the account is moved to the primary `Persistence`. + +If no persistence is provided, the SDK falls back on [inMemoryPersistence](./auth.md#inmemorypersistence). + +Signature: + +```typescript +persistence?: Persistence | Persistence[]; +``` + +## Dependencies.popupRedirectResolver + +The [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) to use. This value depends on the platform. Options are [browserPopupRedirectResolver](./auth.md#browserpopupredirectresolver) and [cordovaPopupRedirectResolver](./auth.md#cordovapopupredirectresolver). This field is optional if neither [signInWithPopup()](./auth.md#signinwithpopup) or [signInWithRedirect()](./auth.md#signinwithredirect) are being used. + +Signature: + +```typescript +popupRedirectResolver?: PopupRedirectResolver; +``` diff --git a/docs-devsite/auth.emailauthcredential.md b/docs-devsite/auth.emailauthcredential.md new file mode 100644 index 00000000000..5d322574b02 --- /dev/null +++ b/docs-devsite/auth.emailauthcredential.md @@ -0,0 +1,69 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# EmailAuthCredential class +Interface that represents the credentials returned by [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) for [ProviderId](./auth.md#providerid).PASSWORD + +Covers both [SignInMethod](./auth.md#signinmethod).EMAIL\_PASSWORD and [SignInMethod](./auth.md#signinmethod).EMAIL\_LINK. + +The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `EmailAuthCredential` class. + +Signature: + +```typescript +export declare class EmailAuthCredential extends AuthCredential +``` +Extends: [AuthCredential](./auth.authcredential.md#authcredential_class) + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [fromJSON(json)](./auth.emailauthcredential.md#emailauthcredentialfromjson) | static | Static method to deserialize a JSON representation of an object into an [AuthCredential](./auth.authcredential.md#authcredential_class). | +| [toJSON()](./auth.emailauthcredential.md#emailauthcredentialtojson) | | Returns a JSON-serializable representation of this object. | + +## EmailAuthCredential.fromJSON() + +Static method to deserialize a JSON representation of an object into an [AuthCredential](./auth.authcredential.md#authcredential_class). + +Signature: + +```typescript +static fromJSON(json: object | string): EmailAuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| json | object \| string | Either object or the stringified representation of the object. When string is provided, JSON.parse would be called first. | + +Returns: + +[EmailAuthCredential](./auth.emailauthcredential.md#emailauthcredential_class) \| null + +If the JSON input does not represent an [AuthCredential](./auth.authcredential.md#authcredential_class), null is returned. + +## EmailAuthCredential.toJSON() + +Returns a JSON-serializable representation of this object. + +Signature: + +```typescript +toJSON(): object; +``` +Returns: + +object + +a JSON-serializable representation of this object. + diff --git a/docs-devsite/auth.emailauthprovider.md b/docs-devsite/auth.emailauthprovider.md new file mode 100644 index 00000000000..c1834b1b8c4 --- /dev/null +++ b/docs-devsite/auth.emailauthprovider.md @@ -0,0 +1,159 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# EmailAuthProvider class +Provider for generating [EmailAuthCredential](./auth.emailauthcredential.md#emailauthcredential_class). + +Signature: + +```typescript +export declare class EmailAuthProvider implements AuthProvider +``` +Implements: [AuthProvider](./auth.authprovider.md#authprovider_interface) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [EMAIL\_LINK\_SIGN\_IN\_METHOD](./auth.emailauthprovider.md#emailauthprovideremail_link_sign_in_method) | static | 'emailLink' | Always set to [SignInMethod](./auth.md#signinmethod).EMAIL\_LINK. | +| [EMAIL\_PASSWORD\_SIGN\_IN\_METHOD](./auth.emailauthprovider.md#emailauthprovideremail_password_sign_in_method) | static | 'password' | Always set to [SignInMethod](./auth.md#signinmethod).EMAIL\_PASSWORD. | +| [PROVIDER\_ID](./auth.emailauthprovider.md#emailauthproviderprovider_id) | static | 'password' | Always set to [ProviderId](./auth.md#providerid).PASSWORD, even for email link. | +| [providerId](./auth.emailauthprovider.md#emailauthproviderproviderid) | | "password" | Always set to [ProviderId](./auth.md#providerid).PASSWORD, even for email link. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [credential(email, password)](./auth.emailauthprovider.md#emailauthprovidercredential) | static | Initialize an [AuthCredential](./auth.authcredential.md#authcredential_class) using an email and password. | +| [credentialWithLink(email, emailLink)](./auth.emailauthprovider.md#emailauthprovidercredentialwithlink) | static | Initialize an [AuthCredential](./auth.authcredential.md#authcredential_class) using an email and an email link after a sign in with email link operation. | + +## EmailAuthProvider.EMAIL\_LINK\_SIGN\_IN\_METHOD + +Always set to [SignInMethod](./auth.md#signinmethod).EMAIL\_LINK. + +Signature: + +```typescript +static readonly EMAIL_LINK_SIGN_IN_METHOD: 'emailLink'; +``` + +## EmailAuthProvider.EMAIL\_PASSWORD\_SIGN\_IN\_METHOD + +Always set to [SignInMethod](./auth.md#signinmethod).EMAIL\_PASSWORD. + +Signature: + +```typescript +static readonly EMAIL_PASSWORD_SIGN_IN_METHOD: 'password'; +``` + +## EmailAuthProvider.PROVIDER\_ID + +Always set to [ProviderId](./auth.md#providerid).PASSWORD, even for email link. + +Signature: + +```typescript +static readonly PROVIDER_ID: 'password'; +``` + +## EmailAuthProvider.providerId + +Always set to [ProviderId](./auth.md#providerid).PASSWORD, even for email link. + +Signature: + +```typescript +readonly providerId: "password"; +``` + +## EmailAuthProvider.credential() + +Initialize an [AuthCredential](./auth.authcredential.md#authcredential_class) using an email and password. + +Signature: + +```typescript +static credential(email: string, password: string): EmailAuthCredential; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| email | string | Email address. | +| password | string | User account password. | + +Returns: + +[EmailAuthCredential](./auth.emailauthcredential.md#emailauthcredential_class) + +The auth provider credential. + +### Example 1 + + +```javascript +const authCredential = EmailAuthProvider.credential(email, password); +const userCredential = await signInWithCredential(auth, authCredential); + +``` + +### Example 2 + + +```javascript +const userCredential = await signInWithEmailAndPassword(auth, email, password); + +``` + +## EmailAuthProvider.credentialWithLink() + +Initialize an [AuthCredential](./auth.authcredential.md#authcredential_class) using an email and an email link after a sign in with email link operation. + +Signature: + +```typescript +static credentialWithLink(email: string, emailLink: string): EmailAuthCredential; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| email | string | Email address. | +| emailLink | string | Sign-in email link. | + +Returns: + +[EmailAuthCredential](./auth.emailauthcredential.md#emailauthcredential_class) + +- The auth provider credential. + +### Example 1 + + +```javascript +const authCredential = EmailAuthProvider.credentialWithLink(auth, email, emailLink); +const userCredential = await signInWithCredential(auth, authCredential); + +``` + +### Example 2 + + +```javascript +await sendSignInLinkToEmail(auth, email); +// Obtain emailLink from user. +const userCredential = await signInWithEmailLink(auth, email, emailLink); + +``` + diff --git a/docs-devsite/auth.emulatorconfig.md b/docs-devsite/auth.emulatorconfig.md new file mode 100644 index 00000000000..23f052c8dc4 --- /dev/null +++ b/docs-devsite/auth.emulatorconfig.md @@ -0,0 +1,70 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# EmulatorConfig interface +Configuration of Firebase Authentication Emulator. + +Signature: + +```typescript +export interface EmulatorConfig +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [host](./auth.emulatorconfig.md#emulatorconfighost) | string | The hostname of the emulator, which may be a domain ("localhost"), IPv4 address ("127.0.0.1") or quoted IPv6 address ("\[::1\]"). | +| [options](./auth.emulatorconfig.md#emulatorconfigoptions) | { readonly disableWarnings: boolean; } | The emulator-specific options. | +| [port](./auth.emulatorconfig.md#emulatorconfigport) | number \| null | The port of the emulator, or null if port isn't specified (i.e. protocol default). | +| [protocol](./auth.emulatorconfig.md#emulatorconfigprotocol) | string | The protocol used to communicate with the emulator ("http"/"https"). | + +## EmulatorConfig.host + +The hostname of the emulator, which may be a domain ("localhost"), IPv4 address ("127.0.0.1") or quoted IPv6 address ("\[::1\]"). + +Signature: + +```typescript +readonly host: string; +``` + +## EmulatorConfig.options + +The emulator-specific options. + +Signature: + +```typescript +readonly options: { + readonly disableWarnings: boolean; + }; +``` + +## EmulatorConfig.port + +The port of the emulator, or null if port isn't specified (i.e. protocol default). + +Signature: + +```typescript +readonly port: number | null; +``` + +## EmulatorConfig.protocol + +The protocol used to communicate with the emulator ("http"/"https"). + +Signature: + +```typescript +readonly protocol: string; +``` diff --git a/docs-devsite/auth.facebookauthprovider.md b/docs-devsite/auth.facebookauthprovider.md new file mode 100644 index 00000000000..71ac4eea79c --- /dev/null +++ b/docs-devsite/auth.facebookauthprovider.md @@ -0,0 +1,182 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FacebookAuthProvider class +Provider for generating an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).FACEBOOK. + +Signature: + +```typescript +export declare class FacebookAuthProvider extends BaseOAuthProvider +``` +Extends: BaseOAuthProvider + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)()](./auth.facebookauthprovider.md#facebookauthproviderconstructor) | | Constructs a new instance of the FacebookAuthProvider class | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [FACEBOOK\_SIGN\_IN\_METHOD](./auth.facebookauthprovider.md#facebookauthproviderfacebook_sign_in_method) | static | 'facebook.com' | Always set to [SignInMethod](./auth.md#signinmethod).FACEBOOK. | +| [PROVIDER\_ID](./auth.facebookauthprovider.md#facebookauthproviderprovider_id) | static | 'facebook.com' | Always set to [ProviderId](./auth.md#providerid).FACEBOOK. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [credential(accessToken)](./auth.facebookauthprovider.md#facebookauthprovidercredential) | static | Creates a credential for Facebook. | +| [credentialFromError(error)](./auth.facebookauthprovider.md#facebookauthprovidercredentialfromerror) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. | +| [credentialFromResult(userCredential)](./auth.facebookauthprovider.md#facebookauthprovidercredentialfromresult) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). | + +## FacebookAuthProvider.(constructor) + +Constructs a new instance of the `FacebookAuthProvider` class + +Signature: + +```typescript +constructor(); +``` + +## FacebookAuthProvider.FACEBOOK\_SIGN\_IN\_METHOD + +Always set to [SignInMethod](./auth.md#signinmethod).FACEBOOK. + +Signature: + +```typescript +static readonly FACEBOOK_SIGN_IN_METHOD: 'facebook.com'; +``` + +## FacebookAuthProvider.PROVIDER\_ID + +Always set to [ProviderId](./auth.md#providerid).FACEBOOK. + +Signature: + +```typescript +static readonly PROVIDER_ID: 'facebook.com'; +``` + +## FacebookAuthProvider.credential() + +Creates a credential for Facebook. + +Signature: + +```typescript +static credential(accessToken: string): OAuthCredential; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| accessToken | string | Facebook access token. | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) + +### Example + + +```javascript +// `event` from the Facebook auth.authResponseChange callback. +const credential = FacebookAuthProvider.credential(event.authResponse.accessToken); +const result = await signInWithCredential(credential); + +``` + +## FacebookAuthProvider.credentialFromError() + +Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. + +Signature: + +```typescript +static credentialFromError(error: FirebaseError): OAuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null + +## FacebookAuthProvider.credentialFromResult() + +Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). + +Signature: + +```typescript +static credentialFromResult(userCredential: UserCredential): OAuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null + +### Example 1 + + +```javascript +// Sign in using a redirect. +const provider = new FacebookAuthProvider(); +// Start a sign in process for an unauthenticated user. +provider.addScope('user_birthday'); +await signInWithRedirect(auth, provider); +// This will trigger a full page redirect away from your app + +// After returning from the redirect when your app initializes you can obtain the result +const result = await getRedirectResult(auth); +if (result) { + // This is the signed-in user + const user = result.user; + // This gives you a Facebook Access Token. + const credential = FacebookAuthProvider.credentialFromResult(result); + const token = credential.accessToken; +} + +``` + +### Example 2 + + +```javascript +// Sign in using a popup. +const provider = new FacebookAuthProvider(); +provider.addScope('user_birthday'); +const result = await signInWithPopup(auth, provider); + +// The signed-in user info. +const user = result.user; +// This gives you a Facebook Access Token. +const credential = FacebookAuthProvider.credentialFromResult(result); +const token = credential.accessToken; + +``` + diff --git a/docs-devsite/auth.githubauthprovider.md b/docs-devsite/auth.githubauthprovider.md new file mode 100644 index 00000000000..d2e04bc8125 --- /dev/null +++ b/docs-devsite/auth.githubauthprovider.md @@ -0,0 +1,174 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# GithubAuthProvider class +Provider for generating an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).GITHUB. + +GitHub requires an OAuth 2.0 redirect, so you can either handle the redirect directly, or use the [signInWithPopup()](./auth.md#signinwithpopup) handler: + +Signature: + +```typescript +export declare class GithubAuthProvider extends BaseOAuthProvider +``` +Extends: BaseOAuthProvider + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)()](./auth.githubauthprovider.md#githubauthproviderconstructor) | | Constructs a new instance of the GithubAuthProvider class | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [GITHUB\_SIGN\_IN\_METHOD](./auth.githubauthprovider.md#githubauthprovidergithub_sign_in_method) | static | 'github.com' | Always set to [SignInMethod](./auth.md#signinmethod).GITHUB. | +| [PROVIDER\_ID](./auth.githubauthprovider.md#githubauthproviderprovider_id) | static | 'github.com' | Always set to [ProviderId](./auth.md#providerid).GITHUB. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [credential(accessToken)](./auth.githubauthprovider.md#githubauthprovidercredential) | static | Creates a credential for Github. | +| [credentialFromError(error)](./auth.githubauthprovider.md#githubauthprovidercredentialfromerror) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. | +| [credentialFromResult(userCredential)](./auth.githubauthprovider.md#githubauthprovidercredentialfromresult) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). | + +## GithubAuthProvider.(constructor) + +Constructs a new instance of the `GithubAuthProvider` class + +Signature: + +```typescript +constructor(); +``` + +## GithubAuthProvider.GITHUB\_SIGN\_IN\_METHOD + +Always set to [SignInMethod](./auth.md#signinmethod).GITHUB. + +Signature: + +```typescript +static readonly GITHUB_SIGN_IN_METHOD: 'github.com'; +``` + +## GithubAuthProvider.PROVIDER\_ID + +Always set to [ProviderId](./auth.md#providerid).GITHUB. + +Signature: + +```typescript +static readonly PROVIDER_ID: 'github.com'; +``` + +## GithubAuthProvider.credential() + +Creates a credential for Github. + +Signature: + +```typescript +static credential(accessToken: string): OAuthCredential; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| accessToken | string | Github access token. | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) + +## GithubAuthProvider.credentialFromError() + +Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. + +Signature: + +```typescript +static credentialFromError(error: FirebaseError): OAuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null + +## GithubAuthProvider.credentialFromResult() + +Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). + +Signature: + +```typescript +static credentialFromResult(userCredential: UserCredential): OAuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null + +### Example 1 + + +```javascript +// Sign in using a redirect. +const provider = new GithubAuthProvider(); +// Start a sign in process for an unauthenticated user. +provider.addScope('repo'); +await signInWithRedirect(auth, provider); +// This will trigger a full page redirect away from your app + +// After returning from the redirect when your app initializes you can obtain the result +const result = await getRedirectResult(auth); +if (result) { + // This is the signed-in user + const user = result.user; + // This gives you a Github Access Token. + const credential = GithubAuthProvider.credentialFromResult(result); + const token = credential.accessToken; +} + +``` + +### Example 2 + + +```javascript +// Sign in using a popup. +const provider = new GithubAuthProvider(); +provider.addScope('repo'); +const result = await signInWithPopup(auth, provider); + +// The signed-in user info. +const user = result.user; +// This gives you a Github Access Token. +const credential = GithubAuthProvider.credentialFromResult(result); +const token = credential.accessToken; + +``` + diff --git a/docs-devsite/auth.googleauthprovider.md b/docs-devsite/auth.googleauthprovider.md new file mode 100644 index 00000000000..2e14c0ff88e --- /dev/null +++ b/docs-devsite/auth.googleauthprovider.md @@ -0,0 +1,185 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# GoogleAuthProvider class +Provider for generating an an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).GOOGLE. + +Signature: + +```typescript +export declare class GoogleAuthProvider extends BaseOAuthProvider +``` +Extends: BaseOAuthProvider + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)()](./auth.googleauthprovider.md#googleauthproviderconstructor) | | Constructs a new instance of the GoogleAuthProvider class | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [GOOGLE\_SIGN\_IN\_METHOD](./auth.googleauthprovider.md#googleauthprovidergoogle_sign_in_method) | static | 'google.com' | Always set to [SignInMethod](./auth.md#signinmethod).GOOGLE. | +| [PROVIDER\_ID](./auth.googleauthprovider.md#googleauthproviderprovider_id) | static | 'google.com' | Always set to [ProviderId](./auth.md#providerid).GOOGLE. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [credential(idToken, accessToken)](./auth.googleauthprovider.md#googleauthprovidercredential) | static | Creates a credential for Google. At least one of ID token and access token is required. | +| [credentialFromError(error)](./auth.googleauthprovider.md#googleauthprovidercredentialfromerror) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. | +| [credentialFromResult(userCredential)](./auth.googleauthprovider.md#googleauthprovidercredentialfromresult) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). | + +## GoogleAuthProvider.(constructor) + +Constructs a new instance of the `GoogleAuthProvider` class + +Signature: + +```typescript +constructor(); +``` + +## GoogleAuthProvider.GOOGLE\_SIGN\_IN\_METHOD + +Always set to [SignInMethod](./auth.md#signinmethod).GOOGLE. + +Signature: + +```typescript +static readonly GOOGLE_SIGN_IN_METHOD: 'google.com'; +``` + +## GoogleAuthProvider.PROVIDER\_ID + +Always set to [ProviderId](./auth.md#providerid).GOOGLE. + +Signature: + +```typescript +static readonly PROVIDER_ID: 'google.com'; +``` + +## GoogleAuthProvider.credential() + +Creates a credential for Google. At least one of ID token and access token is required. + +Signature: + +```typescript +static credential(idToken?: string | null, accessToken?: string | null): OAuthCredential; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| idToken | string \| null | Google ID token. | +| accessToken | string \| null | Google access token. | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) + +### Example + + +```javascript +// \`googleUser\` from the onsuccess Google Sign In callback. +const credential = GoogleAuthProvider.credential(googleUser.getAuthResponse().id_token); +const result = await signInWithCredential(credential); + +``` + +## GoogleAuthProvider.credentialFromError() + +Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. + +Signature: + +```typescript +static credentialFromError(error: FirebaseError): OAuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null + +## GoogleAuthProvider.credentialFromResult() + +Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). + +Signature: + +```typescript +static credentialFromResult(userCredential: UserCredential): OAuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null + +### Example 1 + + +```javascript +// Sign in using a redirect. +const provider = new GoogleAuthProvider(); +// Start a sign in process for an unauthenticated user. +provider.addScope('profile'); +provider.addScope('email'); +await signInWithRedirect(auth, provider); +// This will trigger a full page redirect away from your app + +// After returning from the redirect when your app initializes you can obtain the result +const result = await getRedirectResult(auth); +if (result) { + // This is the signed-in user + const user = result.user; + // This gives you a Google Access Token. + const credential = GoogleAuthProvider.credentialFromResult(result); + const token = credential.accessToken; +} + +``` + +### Example 2 + + +```javascript +// Sign in using a popup. +const provider = new GoogleAuthProvider(); +provider.addScope('profile'); +provider.addScope('email'); +const result = await signInWithPopup(auth, provider); + +// The signed-in user info. +const user = result.user; +// This gives you a Google Access Token. +const credential = GoogleAuthProvider.credentialFromResult(result); +const token = credential.accessToken; + +``` + diff --git a/docs-devsite/auth.idtokenresult.md b/docs-devsite/auth.idtokenresult.md new file mode 100644 index 00000000000..f000df924d9 --- /dev/null +++ b/docs-devsite/auth.idtokenresult.md @@ -0,0 +1,109 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# IdTokenResult interface +Interface representing ID token result obtained from [User.getIdTokenResult()](./auth.user.md#usergetidtokenresult). + +`IdTokenResult` contains the ID token JWT string and other helper properties for getting different data associated with the token as well as all the decoded payload claims. + +Note that these claims are not to be trusted as they are parsed client side. Only server side verification can guarantee the integrity of the token claims. + +Signature: + +```typescript +export interface IdTokenResult +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [authTime](./auth.idtokenresult.md#idtokenresultauthtime) | string | The authentication time formatted as a UTC string. | +| [claims](./auth.idtokenresult.md#idtokenresultclaims) | [ParsedToken](./auth.parsedtoken.md#parsedtoken_interface) | The entire payload claims of the ID token including the standard reserved claims as well as the custom claims. | +| [expirationTime](./auth.idtokenresult.md#idtokenresultexpirationtime) | string | The ID token expiration time formatted as a UTC string. | +| [issuedAtTime](./auth.idtokenresult.md#idtokenresultissuedattime) | string | The ID token issuance time formatted as a UTC string. | +| [signInProvider](./auth.idtokenresult.md#idtokenresultsigninprovider) | string \| null | The sign-in provider through which the ID token was obtained (anonymous, custom, phone, password, etc). | +| [signInSecondFactor](./auth.idtokenresult.md#idtokenresultsigninsecondfactor) | string \| null | The type of second factor associated with this session, provided the user was multi-factor authenticated (eg. phone, etc). | +| [token](./auth.idtokenresult.md#idtokenresulttoken) | string | The Firebase Auth ID token JWT string. | + +## IdTokenResult.authTime + +The authentication time formatted as a UTC string. + +This is the time the user authenticated (signed in) and not the time the token was refreshed. + +Signature: + +```typescript +authTime: string; +``` + +## IdTokenResult.claims + +The entire payload claims of the ID token including the standard reserved claims as well as the custom claims. + +Signature: + +```typescript +claims: ParsedToken; +``` + +## IdTokenResult.expirationTime + +The ID token expiration time formatted as a UTC string. + +Signature: + +```typescript +expirationTime: string; +``` + +## IdTokenResult.issuedAtTime + +The ID token issuance time formatted as a UTC string. + +Signature: + +```typescript +issuedAtTime: string; +``` + +## IdTokenResult.signInProvider + +The sign-in provider through which the ID token was obtained (anonymous, custom, phone, password, etc). + +Note, this does not map to provider IDs. + +Signature: + +```typescript +signInProvider: string | null; +``` + +## IdTokenResult.signInSecondFactor + +The type of second factor associated with this session, provided the user was multi-factor authenticated (eg. phone, etc). + +Signature: + +```typescript +signInSecondFactor: string | null; +``` + +## IdTokenResult.token + +The Firebase Auth ID token JWT string. + +Signature: + +```typescript +token: string; +``` diff --git a/docs-devsite/auth.md b/docs-devsite/auth.md new file mode 100644 index 00000000000..f0f9029c225 --- /dev/null +++ b/docs-devsite/auth.md @@ -0,0 +1,1992 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# auth package +Firebase Authentication + +## Functions + +| Function | Description | +| --- | --- | +| function(app...) | +| [getAuth(app)](./auth.md#getauth) | Returns the Auth instance associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). If no instance exists, initializes an Auth instance with platform-specific default dependencies. | +| [initializeAuth(app, deps)](./auth.md#initializeauth) | Initializes an [Auth](./auth.auth.md#auth_interface) instance with fine-grained control over [Dependencies](./auth.dependencies.md#dependencies_interface). | +| function(storage...) | +| [getReactNativePersistence(storage)](./auth.md#getreactnativepersistence) | Returns a persistence object that wraps AsyncStorage imported from react-native or @react-native-community/async-storage, and can be used in the persistence dependency field in [initializeAuth()](./auth.md#initializeauth). | +| function(auth...) | +| [applyActionCode(auth, oobCode)](./auth.md#applyactioncode) | Applies a verification code sent to the user by email or other out-of-band mechanism. | +| [beforeAuthStateChanged(auth, callback, onAbort)](./auth.md#beforeauthstatechanged) | Adds a blocking callback that runs before an auth state change sets a new user. | +| [checkActionCode(auth, oobCode)](./auth.md#checkactioncode) | Checks a verification code sent to the user by email or other out-of-band mechanism. | +| [confirmPasswordReset(auth, oobCode, newPassword)](./auth.md#confirmpasswordreset) | Completes the password reset process, given a confirmation code and new password. | +| [connectAuthEmulator(auth, url, options)](./auth.md#connectauthemulator) | Changes the [Auth](./auth.auth.md#auth_interface) instance to communicate with the Firebase Auth Emulator, instead of production Firebase Auth services. | +| [createUserWithEmailAndPassword(auth, email, password)](./auth.md#createuserwithemailandpassword) | Creates a new user account associated with the specified email address and password. | +| [fetchSignInMethodsForEmail(auth, email)](./auth.md#fetchsigninmethodsforemail) | Gets the list of possible sign in methods for the given email address. | +| [getMultiFactorResolver(auth, error)](./auth.md#getmultifactorresolver) | Provides a [MultiFactorResolver](./auth.multifactorresolver.md#multifactorresolver_interface) suitable for completion of a multi-factor flow. | +| [getRedirectResult(auth, resolver)](./auth.md#getredirectresult) | Returns a [UserCredential](./auth.usercredential.md#usercredential_interface) from the redirect-based sign-in flow. | +| [isSignInWithEmailLink(auth, emailLink)](./auth.md#issigninwithemaillink) | Checks if an incoming link is a sign-in with email link suitable for [signInWithEmailLink()](./auth.md#signinwithemaillink). | +| [onAuthStateChanged(auth, nextOrObserver, error, completed)](./auth.md#onauthstatechanged) | Adds an observer for changes to the user's sign-in state. | +| [onIdTokenChanged(auth, nextOrObserver, error, completed)](./auth.md#onidtokenchanged) | Adds an observer for changes to the signed-in user's ID token. | +| [sendPasswordResetEmail(auth, email, actionCodeSettings)](./auth.md#sendpasswordresetemail) | Sends a password reset email to the given email address. | +| [sendSignInLinkToEmail(auth, email, actionCodeSettings)](./auth.md#sendsigninlinktoemail) | Sends a sign-in email link to the user with the specified email. | +| [setPersistence(auth, persistence)](./auth.md#setpersistence) | Changes the type of persistence on the [Auth](./auth.auth.md#auth_interface) instance for the currently saved Auth session and applies this type of persistence for future sign-in requests, including sign-in with redirect requests. | +| [signInAnonymously(auth)](./auth.md#signinanonymously) | Asynchronously signs in as an anonymous user. | +| [signInWithCredential(auth, credential)](./auth.md#signinwithcredential) | Asynchronously signs in with the given credentials. | +| [signInWithCustomToken(auth, customToken)](./auth.md#signinwithcustomtoken) | Asynchronously signs in using a custom token. | +| [signInWithEmailAndPassword(auth, email, password)](./auth.md#signinwithemailandpassword) | Asynchronously signs in using an email and password. | +| [signInWithEmailLink(auth, email, emailLink)](./auth.md#signinwithemaillink) | Asynchronously signs in using an email and sign-in email link. | +| [signInWithPhoneNumber(auth, phoneNumber, appVerifier)](./auth.md#signinwithphonenumber) | Asynchronously signs in using a phone number. | +| [signInWithPopup(auth, provider, resolver)](./auth.md#signinwithpopup) | Authenticates a Firebase client using a popup-based OAuth authentication flow. | +| [signInWithRedirect(auth, provider, resolver)](./auth.md#signinwithredirect) | Authenticates a Firebase client using a full-page redirect flow. | +| [signOut(auth)](./auth.md#signout) | Signs out the current user. | +| [updateCurrentUser(auth, user)](./auth.md#updatecurrentuser) | Asynchronously sets the provided user as [Auth.currentUser](./auth.auth.md#authcurrentuser) on the [Auth](./auth.auth.md#auth_interface) instance. | +| [useDeviceLanguage(auth)](./auth.md#usedevicelanguage) | Sets the current language to the default device/browser preference. | +| [verifyPasswordResetCode(auth, code)](./auth.md#verifypasswordresetcode) | Checks a password reset code sent to the user by email or other out-of-band mechanism. | +| function(link...) | +| [parseActionCodeURL(link)](./auth.md#parseactioncodeurl) | Parses the email action link string and returns an [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) if the link is valid, otherwise returns null. | +| function(user...) | +| [deleteUser(user)](./auth.md#deleteuser) | Deletes and signs out the user. | +| [getIdToken(user, forceRefresh)](./auth.md#getidtoken) | Returns a JSON Web Token (JWT) used to identify the user to a Firebase service. | +| [getIdTokenResult(user, forceRefresh)](./auth.md#getidtokenresult) | Returns a deserialized JSON Web Token (JWT) used to identitfy the user to a Firebase service. | +| [linkWithCredential(user, credential)](./auth.md#linkwithcredential) | Links the user account with the given credentials. | +| [linkWithPhoneNumber(user, phoneNumber, appVerifier)](./auth.md#linkwithphonenumber) | Links the user account with the given phone number. | +| [linkWithPopup(user, provider, resolver)](./auth.md#linkwithpopup) | Links the authenticated provider to the user account using a pop-up based OAuth flow. | +| [linkWithRedirect(user, provider, resolver)](./auth.md#linkwithredirect) | Links the [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) to the user account using a full-page redirect flow. | +| [multiFactor(user)](./auth.md#multifactor) | The [MultiFactorUser](./auth.multifactoruser.md#multifactoruser_interface) corresponding to the user. | +| [reauthenticateWithCredential(user, credential)](./auth.md#reauthenticatewithcredential) | Re-authenticates a user using a fresh credential. | +| [reauthenticateWithPhoneNumber(user, phoneNumber, appVerifier)](./auth.md#reauthenticatewithphonenumber) | Re-authenticates a user using a fresh phone credential. | +| [reauthenticateWithPopup(user, provider, resolver)](./auth.md#reauthenticatewithpopup) | Reauthenticates the current user with the specified [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) using a pop-up based OAuth flow. | +| [reauthenticateWithRedirect(user, provider, resolver)](./auth.md#reauthenticatewithredirect) | Reauthenticates the current user with the specified [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) using a full-page redirect flow. | +| [reload(user)](./auth.md#reload) | Reloads user account data, if signed in. | +| [sendEmailVerification(user, actionCodeSettings)](./auth.md#sendemailverification) | Sends a verification email to a user. | +| [unlink(user, providerId)](./auth.md#unlink) | Unlinks a provider from a user account. | +| [updateEmail(user, newEmail)](./auth.md#updateemail) | Updates the user's email address. | +| [updatePassword(user, newPassword)](./auth.md#updatepassword) | Updates the user's password. | +| [updatePhoneNumber(user, credential)](./auth.md#updatephonenumber) | Updates the user's phone number. | +| [updateProfile(user, { displayName, photoURL: photoUrl })](./auth.md#updateprofile) | Updates a user's profile data. | +| [verifyBeforeUpdateEmail(user, newEmail, actionCodeSettings)](./auth.md#verifybeforeupdateemail) | Sends a verification email to a new email address. | +| function(userCredential...) | +| [getAdditionalUserInfo(userCredential)](./auth.md#getadditionaluserinfo) | Extracts provider specific [AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface) for the given credential. | + +## Classes + +| Class | Description | +| --- | --- | +| [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) | A utility class to parse email action URLs such as password reset, email verification, email link sign in, etc. | +| [AuthCredential](./auth.authcredential.md#authcredential_class) | Interface that represents the credentials returned by an [AuthProvider](./auth.authprovider.md#authprovider_interface). | +| [EmailAuthCredential](./auth.emailauthcredential.md#emailauthcredential_class) | Interface that represents the credentials returned by [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) for [ProviderId](./auth.md#providerid).PASSWORD | +| [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) | Provider for generating [EmailAuthCredential](./auth.emailauthcredential.md#emailauthcredential_class). | +| [FacebookAuthProvider](./auth.facebookauthprovider.md#facebookauthprovider_class) | Provider for generating an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).FACEBOOK. | +| [GithubAuthProvider](./auth.githubauthprovider.md#githubauthprovider_class) | Provider for generating an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).GITHUB. | +| [GoogleAuthProvider](./auth.googleauthprovider.md#googleauthprovider_class) | Provider for generating an an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).GOOGLE. | +| [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) | Represents the OAuth credentials returned by an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). | +| [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) | Provider for generating generic [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). | +| [PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class) | Represents the credentials returned by [PhoneAuthProvider](./auth.phoneauthprovider.md#phoneauthprovider_class). | +| [PhoneAuthProvider](./auth.phoneauthprovider.md#phoneauthprovider_class) | Provider for generating an [PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class). | +| [PhoneMultiFactorGenerator](./auth.phonemultifactorgenerator.md#phonemultifactorgenerator_class) | Provider for generating a [PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface). | +| [RecaptchaVerifier](./auth.recaptchaverifier.md#recaptchaverifier_class) | An [reCAPTCHA](https://www.google.com/recaptcha/)-based application verifier. | +| [SAMLAuthProvider](./auth.samlauthprovider.md#samlauthprovider_class) | An [AuthProvider](./auth.authprovider.md#authprovider_interface) for SAML. | +| [TwitterAuthProvider](./auth.twitterauthprovider.md#twitterauthprovider_class) | Provider for generating an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).TWITTER. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [ActionCodeInfo](./auth.actioncodeinfo.md#actioncodeinfo_interface) | A response from [checkActionCode()](./auth.md#checkactioncode). | +| [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface) | An interface that defines the required continue/state URL with optional Android and iOS bundle identifiers. | +| [AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface) | A structure containing additional user information from a federated identity provider. | +| [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) | A verifier for domain verification and abuse prevention. | +| [Auth](./auth.auth.md#auth_interface) | Interface representing Firebase Auth service. | +| [AuthError](./auth.autherror.md#autherror_interface) | Interface for an Auth error. | +| [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) | A mapping of error codes to error messages. | +| [AuthProvider](./auth.authprovider.md#authprovider_interface) | Interface that represents an auth provider, used to facilitate creating [AuthCredential](./auth.authcredential.md#authcredential_class). | +| [AuthSettings](./auth.authsettings.md#authsettings_interface) | Interface representing an [Auth](./auth.auth.md#auth_interface) instance's settings. | +| [Config](./auth.config.md#config_interface) | Interface representing the Auth config. | +| [ConfirmationResult](./auth.confirmationresult.md#confirmationresult_interface) | A result from a phone number sign-in, link, or reauthenticate call. | +| [Dependencies](./auth.dependencies.md#dependencies_interface) | The dependencies that can be used to initialize an [Auth](./auth.auth.md#auth_interface) instance. | +| [EmulatorConfig](./auth.emulatorconfig.md#emulatorconfig_interface) | Configuration of Firebase Authentication Emulator. | +| [IdTokenResult](./auth.idtokenresult.md#idtokenresult_interface) | Interface representing ID token result obtained from [User.getIdTokenResult()](./auth.user.md#usergetidtokenresult). | +| [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) | The base class for asserting ownership of a second factor. | +| [MultiFactorError](./auth.multifactorerror.md#multifactorerror_interface) | The error thrown when the user needs to provide a second factor to sign in successfully. | +| [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) | A structure containing the information of a second factor entity. | +| [MultiFactorResolver](./auth.multifactorresolver.md#multifactorresolver_interface) | The class used to facilitate recovery from [MultiFactorError](./auth.multifactorerror.md#multifactorerror_interface) when a user needs to provide a second factor to sign in. | +| [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) | An interface defining the multi-factor session object used for enrolling a second factor on a user or helping sign in an enrolled user with a second factor. | +| [MultiFactorUser](./auth.multifactoruser.md#multifactoruser_interface) | An interface that defines the multi-factor related properties and operations pertaining to a [User](./auth.user.md#user_interface). | +| [OAuthCredentialOptions](./auth.oauthcredentialoptions.md#oauthcredentialoptions_interface) | Defines the options for initializing an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). | +| [ParsedToken](./auth.parsedtoken.md#parsedtoken_interface) | Interface representing a parsed ID token. | +| [Persistence](./auth.persistence.md#persistence_interface) | An interface covering the possible persistence mechanism types. | +| [PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface) | The class for asserting ownership of a phone second factor. Provided by [PhoneMultiFactorGenerator.assertion()](./auth.phonemultifactorgenerator.md#phonemultifactorgeneratorassertion). | +| [PhoneMultiFactorEnrollInfoOptions](./auth.phonemultifactorenrollinfooptions.md#phonemultifactorenrollinfooptions_interface) | Options used for enrolling a second factor. | +| [PhoneMultiFactorInfo](./auth.phonemultifactorinfo.md#phonemultifactorinfo_interface) | The subclass of the [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) interface for phone number second factors. The factorId of this second factor is [FactorId](./auth.md#factorid).PHONE. | +| [PhoneMultiFactorSignInInfoOptions](./auth.phonemultifactorsignininfooptions.md#phonemultifactorsignininfooptions_interface) | Options used for signing in with a second factor. | +| [PhoneSingleFactorInfoOptions](./auth.phonesinglefactorinfooptions.md#phonesinglefactorinfooptions_interface) | Options used for single-factor sign-in. | +| [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | A resolver used for handling DOM specific operations like [signInWithPopup()](./auth.md#signinwithpopup) or [signInWithRedirect()](./auth.md#signinwithredirect). | +| [ReactNativeAsyncStorage](./auth.reactnativeasyncstorage.md#reactnativeasyncstorage_interface) | Interface for a supplied AsyncStorage. | +| [RecaptchaParameters](./auth.recaptchaparameters.md#recaptchaparameters_interface) | Interface representing reCAPTCHA parameters.See the \[reCAPTCHA docs\](https://developers.google.com/recaptcha/docs/display\#render\_param) for the list of accepted parameters. All parameters are accepted except for sitekey: Firebase Auth provisions a reCAPTCHA for each project and will configure the site key upon rendering.For an invisible reCAPTCHA, set the size key to invisible. | +| [User](./auth.user.md#user_interface) | A user account. | +| [UserCredential](./auth.usercredential.md#usercredential_interface) | A structure containing a [User](./auth.user.md#user_interface), the [OperationType](./auth.md#operationtype), and the provider ID. | +| [UserInfo](./auth.userinfo.md#userinfo_interface) | User profile information, visible only to the Firebase project's apps. | +| [UserMetadata](./auth.usermetadata.md#usermetadata_interface) | Interface representing a user's metadata. | + +## Variables + +| Variable | Description | +| --- | --- | +| [ActionCodeOperation](./auth.md#actioncodeoperation) | An enumeration of the possible email action types. | +| [AuthErrorCodes](./auth.md#autherrorcodes) | A map of potential Auth error codes, for easier comparison with errors thrown by the SDK. | +| [browserLocalPersistence](./auth.md#browserlocalpersistence) | An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type LOCAL using localStorage for the underlying storage. | +| [browserPopupRedirectResolver](./auth.md#browserpopupredirectresolver) | An implementation of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) suitable for browser based applications. | +| [browserSessionPersistence](./auth.md#browsersessionpersistence) | An implementation of [Persistence](./auth.persistence.md#persistence_interface) of SESSION using sessionStorage for the underlying storage. | +| [cordovaPopupRedirectResolver](./auth.md#cordovapopupredirectresolver) | An implementation of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) suitable for Cordova based applications. | +| [debugErrorMap](./auth.md#debugerrormap) | A verbose error map with detailed descriptions for most error codes.See discussion at [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) | +| [FactorId](./auth.md#factorid) | An enum of factors that may be used for multifactor authentication. | +| [indexedDBLocalPersistence](./auth.md#indexeddblocalpersistence) | An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type LOCAL using indexedDB for the underlying storage. | +| [inMemoryPersistence](./auth.md#inmemorypersistence) | An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type 'NONE'. | +| [OperationType](./auth.md#operationtype) | Enumeration of supported operation types. | +| [prodErrorMap](./auth.md#proderrormap) | A minimal error map with all verbose error messages stripped.See discussion at [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) | +| [ProviderId](./auth.md#providerid) | Enumeration of supported providers. | +| [reactNativeLocalPersistence](./auth.md#reactnativelocalpersistence) | An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type 'LOCAL' for use in React Native environments. | +| [SignInMethod](./auth.md#signinmethod) | Enumeration of supported sign-in methods. | + +## Type Aliases + +| Type Alias | Description | +| --- | --- | +| [CustomParameters](./auth.md#customparameters) | Map of OAuth Custom Parameters. | +| [NextOrObserver](./auth.md#nextorobserver) | Type definition for an event callback. | +| [PhoneInfoOptions](./auth.md#phoneinfooptions) | The information required to verify the ownership of a phone number. | +| [UserProfile](./auth.md#userprofile) | User profile used in [AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface). | + +## getAuth() + +Returns the Auth instance associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). If no instance exists, initializes an Auth instance with platform-specific default dependencies. + +Signature: + +```typescript +export declare function getAuth(app?: FirebaseApp): Auth; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The Firebase App. | + +Returns: + +[Auth](./auth.auth.md#auth_interface) + +## initializeAuth() + +Initializes an [Auth](./auth.auth.md#auth_interface) instance with fine-grained control over [Dependencies](./auth.dependencies.md#dependencies_interface). + +This function allows more control over the [Auth](./auth.auth.md#auth_interface) instance than [getAuth()](./auth.md#getauth). `getAuth` uses platform-specific defaults to supply the [Dependencies](./auth.dependencies.md#dependencies_interface). In general, `getAuth` is the easiest way to initialize Auth and works for most use cases. Use `initializeAuth` if you need control over which persistence layer is used, or to minimize bundle size if you're not using either `signInWithPopup` or `signInWithRedirect`. + +For example, if your app only uses anonymous accounts and you only want accounts saved for the current session, initialize `Auth` with: + +```js +const auth = initializeAuth(app, { + persistence: browserSessionPersistence, + popupRedirectResolver: undefined, +}); + +``` + +Signature: + +```typescript +export declare function initializeAuth(app: FirebaseApp, deps?: Dependencies): Auth; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | | +| deps | [Dependencies](./auth.dependencies.md#dependencies_interface) | | + +Returns: + +[Auth](./auth.auth.md#auth_interface) + +## getReactNativePersistence() + +Returns a persistence object that wraps `AsyncStorage` imported from `react-native` or `@react-native-community/async-storage`, and can be used in the persistence dependency field in [initializeAuth()](./auth.md#initializeauth). + +Signature: + +```typescript +export declare function getReactNativePersistence(storage: ReactNativeAsyncStorage): Persistence; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| storage | [ReactNativeAsyncStorage](./auth.reactnativeasyncstorage.md#reactnativeasyncstorage_interface) | | + +Returns: + +[Persistence](./auth.persistence.md#persistence_interface) + +## applyActionCode() + +Applies a verification code sent to the user by email or other out-of-band mechanism. + +Signature: + +```typescript +export declare function applyActionCode(auth: Auth, oobCode: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| oobCode | string | A verification code sent to the user. | + +Returns: + +Promise<void> + +## beforeAuthStateChanged() + +Adds a blocking callback that runs before an auth state change sets a new user. + +Signature: + +```typescript +export declare function beforeAuthStateChanged(auth: Auth, callback: (user: User | null) => void | Promise, onAbort?: () => void): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| callback | (user: [User](./auth.user.md#user_interface) \| null) => void \| Promise<void> | callback triggered before new user value is set. If this throws, it blocks the user from being set. | +| onAbort | () => void | callback triggered if a later beforeAuthStateChanged() callback throws, allowing you to undo any side effects. | + +Returns: + +[Unsubscribe](./util.md#unsubscribe) + +## checkActionCode() + +Checks a verification code sent to the user by email or other out-of-band mechanism. + +Signature: + +```typescript +export declare function checkActionCode(auth: Auth, oobCode: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| oobCode | string | A verification code sent to the user. | + +Returns: + +Promise<[ActionCodeInfo](./auth.actioncodeinfo.md#actioncodeinfo_interface)> + +metadata about the code. + +## confirmPasswordReset() + +Completes the password reset process, given a confirmation code and new password. + +Signature: + +```typescript +export declare function confirmPasswordReset(auth: Auth, oobCode: string, newPassword: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| oobCode | string | A confirmation code sent to the user. | +| newPassword | string | The new password. | + +Returns: + +Promise<void> + +## connectAuthEmulator() + +Changes the [Auth](./auth.auth.md#auth_interface) instance to communicate with the Firebase Auth Emulator, instead of production Firebase Auth services. + +This must be called synchronously immediately following the first call to [initializeAuth()](./auth.md#initializeauth). Do not use with production credentials as emulator traffic is not encrypted. + +Signature: + +```typescript +export declare function connectAuthEmulator(auth: Auth, url: string, options?: { + disableWarnings: boolean; +}): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| url | string | The URL at which the emulator is running (eg, 'http://localhost:9099'). | +| options | { disableWarnings: boolean; } | Optional. options.disableWarnings defaults to false. Set it to true to disable the warning banner attached to the DOM. | + +Returns: + +void + +### Example + + +```javascript +connectAuthEmulator(auth, 'http://127.0.0.1:9099', { disableWarnings: true }); + +``` + +## createUserWithEmailAndPassword() + +Creates a new user account associated with the specified email address and password. + +On successful creation of the user account, this user will also be signed in to your application. + +User account creation can fail if the account already exists or the password is invalid. + +Note: The email address acts as a unique identifier for the user and enables an email-based password reset. This function will create a new user account and set the initial user password. + +Signature: + +```typescript +export declare function createUserWithEmailAndPassword(auth: Auth, email: string, password: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| email | string | The user's email address. | +| password | string | The user's chosen password. | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> + +## fetchSignInMethodsForEmail() + +Gets the list of possible sign in methods for the given email address. + +This is useful to differentiate methods of sign-in for the same provider, eg. [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) which has 2 methods of sign-in, [SignInMethod](./auth.md#signinmethod).EMAIL\_PASSWORD and [SignInMethod](./auth.md#signinmethod).EMAIL\_LINK. + +Signature: + +```typescript +export declare function fetchSignInMethodsForEmail(auth: Auth, email: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| email | string | The user's email address. | + +Returns: + +Promise<string\[\]> + +## getMultiFactorResolver() + +Provides a [MultiFactorResolver](./auth.multifactorresolver.md#multifactorresolver_interface) suitable for completion of a multi-factor flow. + +Signature: + +```typescript +export declare function getMultiFactorResolver(auth: Auth, error: MultiFactorError): MultiFactorResolver; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| error | [MultiFactorError](./auth.multifactorerror.md#multifactorerror_interface) | The [MultiFactorError](./auth.multifactorerror.md#multifactorerror_interface) raised during a sign-in, or reauthentication operation. | + +Returns: + +[MultiFactorResolver](./auth.multifactorresolver.md#multifactorresolver_interface) + +## getRedirectResult() + +Returns a [UserCredential](./auth.usercredential.md#usercredential_interface) from the redirect-based sign-in flow. + +If sign-in succeeded, returns the signed in user. If sign-in was unsuccessful, fails with an error. If no redirect operation was called, returns `null`. + +Signature: + +```typescript +export declare function getRedirectResult(auth: Auth, resolver?: PopupRedirectResolver): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface) \| null> + +### Example + + +```javascript +// Sign in using a redirect. +const provider = new FacebookAuthProvider(); +// You can add additional scopes to the provider: +provider.addScope('user_birthday'); +// Start a sign in process for an unauthenticated user. +await signInWithRedirect(auth, provider); +// This will trigger a full page redirect away from your app + +// After returning from the redirect when your app initializes you can obtain the result +const result = await getRedirectResult(auth); +if (result) { + // This is the signed-in user + const user = result.user; + // This gives you a Facebook Access Token. + const credential = provider.credentialFromResult(auth, result); + const token = credential.accessToken; +} +// As this API can be used for sign-in, linking and reauthentication, +// check the operationType to determine what triggered this redirect +// operation. +const operationType = result.operationType; + +``` + +## isSignInWithEmailLink() + +Checks if an incoming link is a sign-in with email link suitable for [signInWithEmailLink()](./auth.md#signinwithemaillink). + +Signature: + +```typescript +export declare function isSignInWithEmailLink(auth: Auth, emailLink: string): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| emailLink | string | The link sent to the user's email address. | + +Returns: + +boolean + +## onAuthStateChanged() + +Adds an observer for changes to the user's sign-in state. + +To keep the old behavior, see [onIdTokenChanged()](./auth.md#onidtokenchanged). + +Signature: + +```typescript +export declare function onAuthStateChanged(auth: Auth, nextOrObserver: NextOrObserver, error?: ErrorFn, completed?: CompleteFn): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| nextOrObserver | [NextOrObserver](./auth.md#nextorobserver)<[User](./auth.user.md#user_interface)> | callback triggered on change. | +| error | [ErrorFn](./util.md#errorfn) | Deprecated. This callback is never triggered. Errors on signing in/out can be caught in promises returned from sign-in/sign-out functions. | +| completed | [CompleteFn](./util.md#completefn) | Deprecated. This callback is never triggered. | + +Returns: + +[Unsubscribe](./util.md#unsubscribe) + +## onIdTokenChanged() + +Adds an observer for changes to the signed-in user's ID token. + +This includes sign-in, sign-out, and token refresh events. + +Signature: + +```typescript +export declare function onIdTokenChanged(auth: Auth, nextOrObserver: NextOrObserver, error?: ErrorFn, completed?: CompleteFn): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| nextOrObserver | [NextOrObserver](./auth.md#nextorobserver)<[User](./auth.user.md#user_interface)> | callback triggered on change. | +| error | [ErrorFn](./util.md#errorfn) | Deprecated. This callback is never triggered. Errors on signing in/out can be caught in promises returned from sign-in/sign-out functions. | +| completed | [CompleteFn](./util.md#completefn) | Deprecated. This callback is never triggered. | + +Returns: + +[Unsubscribe](./util.md#unsubscribe) + +## sendPasswordResetEmail() + +Sends a password reset email to the given email address. + +To complete the password reset, call [confirmPasswordReset()](./auth.md#confirmpasswordreset) with the code supplied in the email sent to the user, along with the new password specified by the user. + +Signature: + +```typescript +export declare function sendPasswordResetEmail(auth: Auth, email: string, actionCodeSettings?: ActionCodeSettings): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| email | string | The user's email address. | +| actionCodeSettings | [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface) | The [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface). | + +Returns: + +Promise<void> + +### Example + + +```javascript +const actionCodeSettings = { + url: 'https://www.example.com/?email=user@example.com', + iOS: { + bundleId: 'com.example.ios' + }, + android: { + packageName: 'com.example.android', + installApp: true, + minimumVersion: '12' + }, + handleCodeInApp: true +}; +await sendPasswordResetEmail(auth, 'user@example.com', actionCodeSettings); +// Obtain code from user. +await confirmPasswordReset('user@example.com', code); + +``` + +## sendSignInLinkToEmail() + +Sends a sign-in email link to the user with the specified email. + +The sign-in operation has to always be completed in the app unlike other out of band email actions (password reset and email verifications). This is because, at the end of the flow, the user is expected to be signed in and their Auth state persisted within the app. + +To complete sign in with the email link, call [signInWithEmailLink()](./auth.md#signinwithemaillink) with the email address and the email link supplied in the email sent to the user. + +Signature: + +```typescript +export declare function sendSignInLinkToEmail(auth: Auth, email: string, actionCodeSettings: ActionCodeSettings): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | | +| email | string | The user's email address. | +| actionCodeSettings | [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface) | The [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface). | + +Returns: + +Promise<void> + +### Example + + +```javascript +const actionCodeSettings = { + url: 'https://www.example.com/?email=user@example.com', + iOS: { + bundleId: 'com.example.ios' + }, + android: { + packageName: 'com.example.android', + installApp: true, + minimumVersion: '12' + }, + handleCodeInApp: true +}; +await sendSignInLinkToEmail(auth, 'user@example.com', actionCodeSettings); +// Obtain emailLink from the user. +if(isSignInWithEmailLink(auth, emailLink)) { + await signInWithEmailLink(auth, 'user@example.com', emailLink); +} + +``` + +## setPersistence() + +Changes the type of persistence on the [Auth](./auth.auth.md#auth_interface) instance for the currently saved `Auth` session and applies this type of persistence for future sign-in requests, including sign-in with redirect requests. + +This makes it easy for a user signing in to specify whether their session should be remembered or not. It also makes it easier to never persist the `Auth` state for applications that are shared by other users or have sensitive data. + +Signature: + +```typescript +export declare function setPersistence(auth: Auth, persistence: Persistence): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| persistence | [Persistence](./auth.persistence.md#persistence_interface) | The [Persistence](./auth.persistence.md#persistence_interface) to use. | + +Returns: + +Promise<void> + +A `Promise` that resolves once the persistence change has completed + +### Example + + +```javascript +setPersistence(auth, browserSessionPersistence); + +``` + +## signInAnonymously() + +Asynchronously signs in as an anonymous user. + +If there is already an anonymous user signed in, that user will be returned; otherwise, a new anonymous user identity will be created and returned. + +Signature: + +```typescript +export declare function signInAnonymously(auth: Auth): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> + +## signInWithCredential() + +Asynchronously signs in with the given credentials. + +An [AuthProvider](./auth.authprovider.md#authprovider_interface) can be used to generate the credential. + +Signature: + +```typescript +export declare function signInWithCredential(auth: Auth, credential: AuthCredential): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| credential | [AuthCredential](./auth.authcredential.md#authcredential_class) | The auth credential. | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> + +## signInWithCustomToken() + +Asynchronously signs in using a custom token. + +Custom tokens are used to integrate Firebase Auth with existing auth systems, and must be generated by an auth backend using the [createCustomToken](https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#createcustomtoken) method in the [Admin SDK](https://firebase.google.com/docs/auth/admin) . + +Fails with an error if the token is invalid, expired, or not accepted by the Firebase Auth service. + +Signature: + +```typescript +export declare function signInWithCustomToken(auth: Auth, customToken: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| customToken | string | The custom token to sign in with. | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> + +## signInWithEmailAndPassword() + +Asynchronously signs in using an email and password. + +Fails with an error if the email address and password do not match. + +Note: The user's password is NOT the password used to access the user's email account. The email address serves as a unique identifier for the user, and the password is used to access the user's account in your Firebase project. See also: [createUserWithEmailAndPassword()](./auth.md#createuserwithemailandpassword). + +Signature: + +```typescript +export declare function signInWithEmailAndPassword(auth: Auth, email: string, password: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| email | string | The users email address. | +| password | string | The users password. | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> + +## signInWithEmailLink() + +Asynchronously signs in using an email and sign-in email link. + +If no link is passed, the link is inferred from the current URL. + +Fails with an error if the email address is invalid or OTP in email link expires. + +Note: Confirm the link is a sign-in email link before calling this method firebase.auth.Auth.isSignInWithEmailLink. + +Signature: + +```typescript +export declare function signInWithEmailLink(auth: Auth, email: string, emailLink?: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| email | string | The user's email address. | +| emailLink | string | The link sent to the user's email address. | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> + +### Example + + +```javascript +const actionCodeSettings = { + url: 'https://www.example.com/?email=user@example.com', + iOS: { + bundleId: 'com.example.ios' + }, + android: { + packageName: 'com.example.android', + installApp: true, + minimumVersion: '12' + }, + handleCodeInApp: true +}; +await sendSignInLinkToEmail(auth, 'user@example.com', actionCodeSettings); +// Obtain emailLink from the user. +if(isSignInWithEmailLink(auth, emailLink)) { + await signInWithEmailLink(auth, 'user@example.com', emailLink); +} + +``` + +## signInWithPhoneNumber() + +Asynchronously signs in using a phone number. + +This method sends a code via SMS to the given phone number, and returns a [ConfirmationResult](./auth.confirmationresult.md#confirmationresult_interface). After the user provides the code sent to their phone, call [ConfirmationResult.confirm()](./auth.confirmationresult.md#confirmationresultconfirm) with the code to sign the user in. + +For abuse prevention, this method also requires a [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface). This SDK includes a reCAPTCHA-based implementation, [RecaptchaVerifier](./auth.recaptchaverifier.md#recaptchaverifier_class). This function can work on other platforms that do not support the [RecaptchaVerifier](./auth.recaptchaverifier.md#recaptchaverifier_class) (like React Native), but you need to use a third-party [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) implementation. + +Signature: + +```typescript +export declare function signInWithPhoneNumber(auth: Auth, phoneNumber: string, appVerifier: ApplicationVerifier): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| phoneNumber | string | The user's phone number in E.164 format (e.g. +16505550101). | +| appVerifier | [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) | The [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface). | + +Returns: + +Promise<[ConfirmationResult](./auth.confirmationresult.md#confirmationresult_interface)> + +### Example + + +```javascript +// 'recaptcha-container' is the ID of an element in the DOM. +const applicationVerifier = new firebase.auth.RecaptchaVerifier('recaptcha-container'); +const confirmationResult = await signInWithPhoneNumber(auth, phoneNumber, applicationVerifier); +// Obtain a verificationCode from the user. +const credential = await confirmationResult.confirm(verificationCode); + +``` + +## signInWithPopup() + +Authenticates a Firebase client using a popup-based OAuth authentication flow. + +If succeeds, returns the signed in user along with the provider's credential. If sign in was unsuccessful, returns an error object containing additional information about the error. + +Signature: + +```typescript +export declare function signInWithPopup(auth: Auth, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | +| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> + +### Example + + +```javascript +// Sign in using a popup. +const provider = new FacebookAuthProvider(); +const result = await signInWithPopup(auth, provider); + +// The signed-in user info. +const user = result.user; +// This gives you a Facebook Access Token. +const credential = provider.credentialFromResult(auth, result); +const token = credential.accessToken; + +``` + +## signInWithRedirect() + +Authenticates a Firebase client using a full-page redirect flow. + +To handle the results and errors for this operation, refer to [getRedirectResult()](./auth.md#getredirectresult). Follow the [best practices](https://firebase.google.com/docs/auth/web/redirect-best-practices) when using [signInWithRedirect()](./auth.md#signinwithredirect). + +Signature: + +```typescript +export declare function signInWithRedirect(auth: Auth, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | +| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | + +Returns: + +Promise<never> + +### Example + + +```javascript +// Sign in using a redirect. +const provider = new FacebookAuthProvider(); +// You can add additional scopes to the provider: +provider.addScope('user_birthday'); +// Start a sign in process for an unauthenticated user. +await signInWithRedirect(auth, provider); +// This will trigger a full page redirect away from your app + +// After returning from the redirect when your app initializes you can obtain the result +const result = await getRedirectResult(auth); +if (result) { + // This is the signed-in user + const user = result.user; + // This gives you a Facebook Access Token. + const credential = provider.credentialFromResult(auth, result); + const token = credential.accessToken; +} +// As this API can be used for sign-in, linking and reauthentication, +// check the operationType to determine what triggered this redirect +// operation. +const operationType = result.operationType; + +``` + +## signOut() + +Signs out the current user. + +Signature: + +```typescript +export declare function signOut(auth: Auth): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | + +Returns: + +Promise<void> + +## updateCurrentUser() + +Asynchronously sets the provided user as [Auth.currentUser](./auth.auth.md#authcurrentuser) on the [Auth](./auth.auth.md#auth_interface) instance. + +A new instance copy of the user provided will be made and set as currentUser. + +This will trigger [onAuthStateChanged()](./auth.md#onauthstatechanged) and [onIdTokenChanged()](./auth.md#onidtokenchanged) listeners like other sign in methods. + +The operation fails with an error if the user to be updated belongs to a different Firebase project. + +Signature: + +```typescript +export declare function updateCurrentUser(auth: Auth, user: User | null): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| user | [User](./auth.user.md#user_interface) \| null | The new [User](./auth.user.md#user_interface). | + +Returns: + +Promise<void> + +## useDeviceLanguage() + +Sets the current language to the default device/browser preference. + +Signature: + +```typescript +export declare function useDeviceLanguage(auth: Auth): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | + +Returns: + +void + +## verifyPasswordResetCode() + +Checks a password reset code sent to the user by email or other out-of-band mechanism. + +Signature: + +```typescript +export declare function verifyPasswordResetCode(auth: Auth, code: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| code | string | A verification code sent to the user. | + +Returns: + +Promise<string> + +the user's email address if valid. + +## parseActionCodeURL() + +Parses the email action link string and returns an [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) if the link is valid, otherwise returns null. + +Signature: + +```typescript +export declare function parseActionCodeURL(link: string): ActionCodeURL | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| link | string | | + +Returns: + +[ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) \| null + +## deleteUser() + +Deletes and signs out the user. + +Important: this is a security-sensitive operation that requires the user to have recently signed in. If this requirement isn't met, ask the user to authenticate again and then call [reauthenticateWithCredential()](./auth.md#reauthenticatewithcredential). + +Signature: + +```typescript +export declare function deleteUser(user: User): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | + +Returns: + +Promise<void> + +## getIdToken() + +Returns a JSON Web Token (JWT) used to identify the user to a Firebase service. + +Returns the current token if it has not expired or if it will not expire in the next five minutes. Otherwise, this will refresh the token and return a new one. + +Signature: + +```typescript +export declare function getIdToken(user: User, forceRefresh?: boolean): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| forceRefresh | boolean | Force refresh regardless of token expiration. | + +Returns: + +Promise<string> + +## getIdTokenResult() + +Returns a deserialized JSON Web Token (JWT) used to identitfy the user to a Firebase service. + +Returns the current token if it has not expired or if it will not expire in the next five minutes. Otherwise, this will refresh the token and return a new one. + +Signature: + +```typescript +export declare function getIdTokenResult(user: User, forceRefresh?: boolean): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| forceRefresh | boolean | Force refresh regardless of token expiration. | + +Returns: + +Promise<[IdTokenResult](./auth.idtokenresult.md#idtokenresult_interface)> + +## linkWithCredential() + +Links the user account with the given credentials. + +An [AuthProvider](./auth.authprovider.md#authprovider_interface) can be used to generate the credential. + +Signature: + +```typescript +export declare function linkWithCredential(user: User, credential: AuthCredential): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| credential | [AuthCredential](./auth.authcredential.md#authcredential_class) | The auth credential. | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> + +## linkWithPhoneNumber() + +Links the user account with the given phone number. + +Signature: + +```typescript +export declare function linkWithPhoneNumber(user: User, phoneNumber: string, appVerifier: ApplicationVerifier): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| phoneNumber | string | The user's phone number in E.164 format (e.g. +16505550101). | +| appVerifier | [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) | The [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface). | + +Returns: + +Promise<[ConfirmationResult](./auth.confirmationresult.md#confirmationresult_interface)> + +## linkWithPopup() + +Links the authenticated provider to the user account using a pop-up based OAuth flow. + +If the linking is successful, the returned result will contain the user and the provider's credential. + +Signature: + +```typescript +export declare function linkWithPopup(user: User, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | +| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> + +### Example + + +```javascript +// Sign in using some other provider. +const result = await signInWithEmailAndPassword(auth, email, password); +// Link using a popup. +const provider = new FacebookAuthProvider(); +await linkWithPopup(result.user, provider); + +``` + +## linkWithRedirect() + +Links the [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) to the user account using a full-page redirect flow. + +To handle the results and errors for this operation, refer to [getRedirectResult()](./auth.md#getredirectresult). Follow the [best practices](https://firebase.google.com/docs/auth/web/redirect-best-practices) when using [linkWithRedirect()](./auth.md#linkwithredirect). + +Signature: + +```typescript +export declare function linkWithRedirect(user: User, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | +| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | + +Returns: + +Promise<never> + +### Example + + +```javascript +// Sign in using some other provider. +const result = await signInWithEmailAndPassword(auth, email, password); +// Link using a redirect. +const provider = new FacebookAuthProvider(); +await linkWithRedirect(result.user, provider); +// This will trigger a full page redirect away from your app + +// After returning from the redirect when your app initializes you can obtain the result +const result = await getRedirectResult(auth); + +``` + +## multiFactor() + +The [MultiFactorUser](./auth.multifactoruser.md#multifactoruser_interface) corresponding to the user. + +This is used to access all multi-factor properties and operations related to the user. + +Signature: + +```typescript +export declare function multiFactor(user: User): MultiFactorUser; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | + +Returns: + +[MultiFactorUser](./auth.multifactoruser.md#multifactoruser_interface) + +## reauthenticateWithCredential() + +Re-authenticates a user using a fresh credential. + +Use before operations such as [updatePassword()](./auth.md#updatepassword) that require tokens from recent sign-in attempts. This method can be used to recover from a `CREDENTIAL_TOO_OLD_LOGIN_AGAIN` error or a `TOKEN_EXPIRED` error. + +Signature: + +```typescript +export declare function reauthenticateWithCredential(user: User, credential: AuthCredential): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| credential | [AuthCredential](./auth.authcredential.md#authcredential_class) | The auth credential. | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> + +## reauthenticateWithPhoneNumber() + +Re-authenticates a user using a fresh phone credential. + +Use before operations such as [updatePassword()](./auth.md#updatepassword) that require tokens from recent sign-in attempts. + +Signature: + +```typescript +export declare function reauthenticateWithPhoneNumber(user: User, phoneNumber: string, appVerifier: ApplicationVerifier): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| phoneNumber | string | The user's phone number in E.164 format (e.g. +16505550101). | +| appVerifier | [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) | The [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface). | + +Returns: + +Promise<[ConfirmationResult](./auth.confirmationresult.md#confirmationresult_interface)> + +## reauthenticateWithPopup() + +Reauthenticates the current user with the specified [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) using a pop-up based OAuth flow. + +If the reauthentication is successful, the returned result will contain the user and the provider's credential. + +Signature: + +```typescript +export declare function reauthenticateWithPopup(user: User, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | +| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> + +### Example + + +```javascript +// Sign in using a popup. +const provider = new FacebookAuthProvider(); +const result = await signInWithPopup(auth, provider); +// Reauthenticate using a popup. +await reauthenticateWithPopup(result.user, provider); + +``` + +## reauthenticateWithRedirect() + +Reauthenticates the current user with the specified [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) using a full-page redirect flow. + +To handle the results and errors for this operation, refer to [getRedirectResult()](./auth.md#getredirectresult). Follow the [best practices](https://firebase.google.com/docs/auth/web/redirect-best-practices) when using [reauthenticateWithRedirect()](./auth.md#reauthenticatewithredirect). + +Signature: + +```typescript +export declare function reauthenticateWithRedirect(user: User, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | +| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | + +Returns: + +Promise<never> + +### Example + + +```javascript +// Sign in using a redirect. +const provider = new FacebookAuthProvider(); +const result = await signInWithRedirect(auth, provider); +// This will trigger a full page redirect away from your app + +// After returning from the redirect when your app initializes you can obtain the result +const result = await getRedirectResult(auth); +// Reauthenticate using a redirect. +await reauthenticateWithRedirect(result.user, provider); +// This will again trigger a full page redirect away from your app + +// After returning from the redirect when your app initializes you can obtain the result +const result = await getRedirectResult(auth); + +``` + +## reload() + +Reloads user account data, if signed in. + +Signature: + +```typescript +export declare function reload(user: User): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | + +Returns: + +Promise<void> + +## sendEmailVerification() + +Sends a verification email to a user. + +The verification process is completed by calling [applyActionCode()](./auth.md#applyactioncode). + +Signature: + +```typescript +export declare function sendEmailVerification(user: User, actionCodeSettings?: ActionCodeSettings | null): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| actionCodeSettings | [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface) \| null | The [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface). | + +Returns: + +Promise<void> + +### Example + + +```javascript +const actionCodeSettings = { + url: 'https://www.example.com/?email=user@example.com', + iOS: { + bundleId: 'com.example.ios' + }, + android: { + packageName: 'com.example.android', + installApp: true, + minimumVersion: '12' + }, + handleCodeInApp: true +}; +await sendEmailVerification(user, actionCodeSettings); +// Obtain code from the user. +await applyActionCode(auth, code); + +``` + +## unlink() + +Unlinks a provider from a user account. + +Signature: + +```typescript +export declare function unlink(user: User, providerId: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| providerId | string | The provider to unlink. | + +Returns: + +Promise<[User](./auth.user.md#user_interface)> + +## updateEmail() + +Updates the user's email address. + +An email will be sent to the original email address (if it was set) that allows to revoke the email address change, in order to protect them from account hijacking. + +Important: this is a security sensitive operation that requires the user to have recently signed in. If this requirement isn't met, ask the user to authenticate again and then call [reauthenticateWithCredential()](./auth.md#reauthenticatewithcredential). + +Signature: + +```typescript +export declare function updateEmail(user: User, newEmail: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| newEmail | string | The new email address. | + +Returns: + +Promise<void> + +## updatePassword() + +Updates the user's password. + +Important: this is a security sensitive operation that requires the user to have recently signed in. If this requirement isn't met, ask the user to authenticate again and then call [reauthenticateWithCredential()](./auth.md#reauthenticatewithcredential). + +Signature: + +```typescript +export declare function updatePassword(user: User, newPassword: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| newPassword | string | The new password. | + +Returns: + +Promise<void> + +## updatePhoneNumber() + +Updates the user's phone number. + +Signature: + +```typescript +export declare function updatePhoneNumber(user: User, credential: PhoneAuthCredential): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| credential | [PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class) | A credential authenticating the new phone number. | + +Returns: + +Promise<void> + +### Example + + +``` +// 'recaptcha-container' is the ID of an element in the DOM. +const applicationVerifier = new RecaptchaVerifier('recaptcha-container'); +const provider = new PhoneAuthProvider(auth); +const verificationId = await provider.verifyPhoneNumber('+16505550101', applicationVerifier); +// Obtain the verificationCode from the user. +const phoneCredential = PhoneAuthProvider.credential(verificationId, verificationCode); +await updatePhoneNumber(user, phoneCredential); + +``` + +## updateProfile() + +Updates a user's profile data. + +Signature: + +```typescript +export declare function updateProfile(user: User, { displayName, photoURL: photoUrl }: { + displayName?: string | null; + photoURL?: string | null; +}): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| { displayName, photoURL: photoUrl } | { displayName?: string \| null; photoURL?: string \| null; } | | + +Returns: + +Promise<void> + +## verifyBeforeUpdateEmail() + +Sends a verification email to a new email address. + +The user's email will be updated to the new one after being verified. + +If you have a custom email action handler, you can complete the verification process by calling [applyActionCode()](./auth.md#applyactioncode). + +Signature: + +```typescript +export declare function verifyBeforeUpdateEmail(user: User, newEmail: string, actionCodeSettings?: ActionCodeSettings | null): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| newEmail | string | The new email address to be verified before update. | +| actionCodeSettings | [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface) \| null | The [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface). | + +Returns: + +Promise<void> + +### Example + + +```javascript +const actionCodeSettings = { + url: 'https://www.example.com/?email=user@example.com', + iOS: { + bundleId: 'com.example.ios' + }, + android: { + packageName: 'com.example.android', + installApp: true, + minimumVersion: '12' + }, + handleCodeInApp: true +}; +await verifyBeforeUpdateEmail(user, 'newemail@example.com', actionCodeSettings); +// Obtain code from the user. +await applyActionCode(auth, code); + +``` + +## getAdditionalUserInfo() + +Extracts provider specific [AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface) for the given credential. + +Signature: + +```typescript +export declare function getAdditionalUserInfo(userCredential: UserCredential): AdditionalUserInfo | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | + +Returns: + +[AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface) \| null + +## ActionCodeOperation + +An enumeration of the possible email action types. + +Signature: + +```typescript +ActionCodeOperation: { + readonly EMAIL_SIGNIN: "EMAIL_SIGNIN"; + readonly PASSWORD_RESET: "PASSWORD_RESET"; + readonly RECOVER_EMAIL: "RECOVER_EMAIL"; + readonly REVERT_SECOND_FACTOR_ADDITION: "REVERT_SECOND_FACTOR_ADDITION"; + readonly VERIFY_AND_CHANGE_EMAIL: "VERIFY_AND_CHANGE_EMAIL"; + readonly VERIFY_EMAIL: "VERIFY_EMAIL"; +} +``` + +## AuthErrorCodes + +A map of potential `Auth` error codes, for easier comparison with errors thrown by the SDK. + +Note that you can't tree-shake individual keys in the map, so by using the map you might substantially increase your bundle size. + +Signature: + +```typescript +AUTH_ERROR_CODES_MAP_DO_NOT_USE_INTERNALLY: { + readonly ADMIN_ONLY_OPERATION: "auth/admin-restricted-operation"; + readonly ARGUMENT_ERROR: "auth/argument-error"; + readonly APP_NOT_AUTHORIZED: "auth/app-not-authorized"; + readonly APP_NOT_INSTALLED: "auth/app-not-installed"; + readonly CAPTCHA_CHECK_FAILED: "auth/captcha-check-failed"; + readonly CODE_EXPIRED: "auth/code-expired"; + readonly CORDOVA_NOT_READY: "auth/cordova-not-ready"; + readonly CORS_UNSUPPORTED: "auth/cors-unsupported"; + readonly CREDENTIAL_ALREADY_IN_USE: "auth/credential-already-in-use"; + readonly CREDENTIAL_MISMATCH: "auth/custom-token-mismatch"; + readonly CREDENTIAL_TOO_OLD_LOGIN_AGAIN: "auth/requires-recent-login"; + readonly DEPENDENT_SDK_INIT_BEFORE_AUTH: "auth/dependent-sdk-initialized-before-auth"; + readonly DYNAMIC_LINK_NOT_ACTIVATED: "auth/dynamic-link-not-activated"; + readonly EMAIL_CHANGE_NEEDS_VERIFICATION: "auth/email-change-needs-verification"; + readonly EMAIL_EXISTS: "auth/email-already-in-use"; + readonly EMULATOR_CONFIG_FAILED: "auth/emulator-config-failed"; + readonly EXPIRED_OOB_CODE: "auth/expired-action-code"; + readonly EXPIRED_POPUP_REQUEST: "auth/cancelled-popup-request"; + readonly INTERNAL_ERROR: "auth/internal-error"; + readonly INVALID_API_KEY: "auth/invalid-api-key"; + readonly INVALID_APP_CREDENTIAL: "auth/invalid-app-credential"; + readonly INVALID_APP_ID: "auth/invalid-app-id"; + readonly INVALID_AUTH: "auth/invalid-user-token"; + readonly INVALID_AUTH_EVENT: "auth/invalid-auth-event"; + readonly INVALID_CERT_HASH: "auth/invalid-cert-hash"; + readonly INVALID_CODE: "auth/invalid-verification-code"; + readonly INVALID_CONTINUE_URI: "auth/invalid-continue-uri"; + readonly INVALID_CORDOVA_CONFIGURATION: "auth/invalid-cordova-configuration"; + readonly INVALID_CUSTOM_TOKEN: "auth/invalid-custom-token"; + readonly INVALID_DYNAMIC_LINK_DOMAIN: "auth/invalid-dynamic-link-domain"; + readonly INVALID_EMAIL: "auth/invalid-email"; + readonly INVALID_EMULATOR_SCHEME: "auth/invalid-emulator-scheme"; + readonly INVALID_IDP_RESPONSE: "auth/invalid-credential"; + readonly INVALID_MESSAGE_PAYLOAD: "auth/invalid-message-payload"; + readonly INVALID_MFA_SESSION: "auth/invalid-multi-factor-session"; + readonly INVALID_OAUTH_CLIENT_ID: "auth/invalid-oauth-client-id"; + readonly INVALID_OAUTH_PROVIDER: "auth/invalid-oauth-provider"; + readonly INVALID_OOB_CODE: "auth/invalid-action-code"; + readonly INVALID_ORIGIN: "auth/unauthorized-domain"; + readonly INVALID_PASSWORD: "auth/wrong-password"; + readonly INVALID_PERSISTENCE: "auth/invalid-persistence-type"; + readonly INVALID_PHONE_NUMBER: "auth/invalid-phone-number"; + readonly INVALID_PROVIDER_ID: "auth/invalid-provider-id"; + readonly INVALID_RECIPIENT_EMAIL: "auth/invalid-recipient-email"; + readonly INVALID_SENDER: "auth/invalid-sender"; + readonly INVALID_SESSION_INFO: "auth/invalid-verification-id"; + readonly INVALID_TENANT_ID: "auth/invalid-tenant-id"; + readonly MFA_INFO_NOT_FOUND: "auth/multi-factor-info-not-found"; + readonly MFA_REQUIRED: "auth/multi-factor-auth-required"; + readonly MISSING_ANDROID_PACKAGE_NAME: "auth/missing-android-pkg-name"; + readonly MISSING_APP_CREDENTIAL: "auth/missing-app-credential"; + readonly MISSING_AUTH_DOMAIN: "auth/auth-domain-config-required"; + readonly MISSING_CODE: "auth/missing-verification-code"; + readonly MISSING_CONTINUE_URI: "auth/missing-continue-uri"; + readonly MISSING_IFRAME_START: "auth/missing-iframe-start"; + readonly MISSING_IOS_BUNDLE_ID: "auth/missing-ios-bundle-id"; + readonly MISSING_OR_INVALID_NONCE: "auth/missing-or-invalid-nonce"; + readonly MISSING_MFA_INFO: "auth/missing-multi-factor-info"; + readonly MISSING_MFA_SESSION: "auth/missing-multi-factor-session"; + readonly MISSING_PHONE_NUMBER: "auth/missing-phone-number"; + readonly MISSING_SESSION_INFO: "auth/missing-verification-id"; + readonly MODULE_DESTROYED: "auth/app-deleted"; + readonly NEED_CONFIRMATION: "auth/account-exists-with-different-credential"; + readonly NETWORK_REQUEST_FAILED: "auth/network-request-failed"; + readonly NULL_USER: "auth/null-user"; + readonly NO_AUTH_EVENT: "auth/no-auth-event"; + readonly NO_SUCH_PROVIDER: "auth/no-such-provider"; + readonly OPERATION_NOT_ALLOWED: "auth/operation-not-allowed"; + readonly OPERATION_NOT_SUPPORTED: "auth/operation-not-supported-in-this-environment"; + readonly POPUP_BLOCKED: "auth/popup-blocked"; + readonly POPUP_CLOSED_BY_USER: "auth/popup-closed-by-user"; + readonly PROVIDER_ALREADY_LINKED: "auth/provider-already-linked"; + readonly QUOTA_EXCEEDED: "auth/quota-exceeded"; + readonly REDIRECT_CANCELLED_BY_USER: "auth/redirect-cancelled-by-user"; + readonly REDIRECT_OPERATION_PENDING: "auth/redirect-operation-pending"; + readonly REJECTED_CREDENTIAL: "auth/rejected-credential"; + readonly SECOND_FACTOR_ALREADY_ENROLLED: "auth/second-factor-already-in-use"; + readonly SECOND_FACTOR_LIMIT_EXCEEDED: "auth/maximum-second-factor-count-exceeded"; + readonly TENANT_ID_MISMATCH: "auth/tenant-id-mismatch"; + readonly TIMEOUT: "auth/timeout"; + readonly TOKEN_EXPIRED: "auth/user-token-expired"; + readonly TOO_MANY_ATTEMPTS_TRY_LATER: "auth/too-many-requests"; + readonly UNAUTHORIZED_DOMAIN: "auth/unauthorized-continue-uri"; + readonly UNSUPPORTED_FIRST_FACTOR: "auth/unsupported-first-factor"; + readonly UNSUPPORTED_PERSISTENCE: "auth/unsupported-persistence-type"; + readonly UNSUPPORTED_TENANT_OPERATION: "auth/unsupported-tenant-operation"; + readonly UNVERIFIED_EMAIL: "auth/unverified-email"; + readonly USER_CANCELLED: "auth/user-cancelled"; + readonly USER_DELETED: "auth/user-not-found"; + readonly USER_DISABLED: "auth/user-disabled"; + readonly USER_MISMATCH: "auth/user-mismatch"; + readonly USER_SIGNED_OUT: "auth/user-signed-out"; + readonly WEAK_PASSWORD: "auth/weak-password"; + readonly WEB_STORAGE_UNSUPPORTED: "auth/web-storage-unsupported"; + readonly ALREADY_INITIALIZED: "auth/already-initialized"; +} +``` + +## browserLocalPersistence + +An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type `LOCAL` using `localStorage` for the underlying storage. + +Signature: + +```typescript +browserLocalPersistence: Persistence +``` + +## browserPopupRedirectResolver + +An implementation of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) suitable for browser based applications. + +Signature: + +```typescript +browserPopupRedirectResolver: PopupRedirectResolver +``` + +## browserSessionPersistence + +An implementation of [Persistence](./auth.persistence.md#persistence_interface) of `SESSION` using `sessionStorage` for the underlying storage. + +Signature: + +```typescript +browserSessionPersistence: Persistence +``` + +## cordovaPopupRedirectResolver + +An implementation of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) suitable for Cordova based applications. + +Signature: + +```typescript +cordovaPopupRedirectResolver: PopupRedirectResolver +``` + +## debugErrorMap + +A verbose error map with detailed descriptions for most error codes. + +See discussion at [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) + +Signature: + +```typescript +debugErrorMap: AuthErrorMap +``` + +## FactorId + +An enum of factors that may be used for multifactor authentication. + +Signature: + +```typescript +FactorId: { + readonly PHONE: "phone"; +} +``` + +## indexedDBLocalPersistence + +An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type `LOCAL` using `indexedDB` for the underlying storage. + +Signature: + +```typescript +indexedDBLocalPersistence: Persistence +``` + +## inMemoryPersistence + +An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type 'NONE'. + +Signature: + +```typescript +inMemoryPersistence: Persistence +``` + +## OperationType + +Enumeration of supported operation types. + +Signature: + +```typescript +OperationType: { + readonly LINK: "link"; + readonly REAUTHENTICATE: "reauthenticate"; + readonly SIGN_IN: "signIn"; +} +``` + +## prodErrorMap + +A minimal error map with all verbose error messages stripped. + +See discussion at [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) + +Signature: + +```typescript +prodErrorMap: AuthErrorMap +``` + +## ProviderId + +Enumeration of supported providers. + +Signature: + +```typescript +ProviderId: { + readonly FACEBOOK: "facebook.com"; + readonly GITHUB: "github.com"; + readonly GOOGLE: "google.com"; + readonly PASSWORD: "password"; + readonly PHONE: "phone"; + readonly TWITTER: "twitter.com"; +} +``` + +## reactNativeLocalPersistence + +An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type 'LOCAL' for use in React Native environments. + +Signature: + +```typescript +reactNativeLocalPersistence: Persistence +``` + +## SignInMethod + +Enumeration of supported sign-in methods. + +Signature: + +```typescript +SignInMethod: { + readonly EMAIL_LINK: "emailLink"; + readonly EMAIL_PASSWORD: "password"; + readonly FACEBOOK: "facebook.com"; + readonly GITHUB: "github.com"; + readonly GOOGLE: "google.com"; + readonly PHONE: "phone"; + readonly TWITTER: "twitter.com"; +} +``` + +## CustomParameters + +Map of OAuth Custom Parameters. + +Signature: + +```typescript +export declare type CustomParameters = Record; +``` + +## NextOrObserver + +Type definition for an event callback. + +Signature: + +```typescript +export declare type NextOrObserver = NextFn | Observer; +``` + +## PhoneInfoOptions + +The information required to verify the ownership of a phone number. + +The information that's required depends on whether you are doing single-factor sign-in, multi-factor enrollment or multi-factor sign-in. + +Signature: + +```typescript +export declare type PhoneInfoOptions = PhoneSingleFactorInfoOptions | PhoneMultiFactorEnrollInfoOptions | PhoneMultiFactorSignInInfoOptions; +``` + +## UserProfile + +User profile used in [AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface). + +Signature: + +```typescript +export declare type UserProfile = Record; +``` diff --git a/docs-devsite/auth.multifactorassertion.md b/docs-devsite/auth.multifactorassertion.md new file mode 100644 index 00000000000..d7937ec1f64 --- /dev/null +++ b/docs-devsite/auth.multifactorassertion.md @@ -0,0 +1,37 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# MultiFactorAssertion interface +The base class for asserting ownership of a second factor. + +This is used to facilitate enrollment of a second factor on an existing user or sign-in of a user who already verified the first factor. + +Signature: + +```typescript +export interface MultiFactorAssertion +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [factorId](./auth.multifactorassertion.md#multifactorassertionfactorid) | typeof [FactorIdMap](./auth.md#factorid)\[keyof typeof [FactorIdMap](./auth.md#factorid)\] | The identifier of the second factor. | + +## MultiFactorAssertion.factorId + +The identifier of the second factor. + +Signature: + +```typescript +readonly factorId: typeof FactorIdMap[keyof typeof FactorIdMap]; +``` diff --git a/docs-devsite/auth.multifactorerror.md b/docs-devsite/auth.multifactorerror.md new file mode 100644 index 00000000000..a13276f5a61 --- /dev/null +++ b/docs-devsite/auth.multifactorerror.md @@ -0,0 +1,67 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# MultiFactorError interface +The error thrown when the user needs to provide a second factor to sign in successfully. + +The error code for this error is `auth/multi-factor-auth-required`. + +Signature: + +```typescript +export interface MultiFactorError extends AuthError +``` +Extends: [AuthError](./auth.autherror.md#autherror_interface) + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [customData](./auth.multifactorerror.md#multifactorerrorcustomdata) | [AuthError](./auth.autherror.md#autherror_interface)\['customData'\] & { readonly operationType: typeof [OperationTypeMap](./auth.md#operationtype)\[keyof typeof [OperationTypeMap](./auth.md#operationtype)\]; } | Details about the MultiFactorError. | + +## MultiFactorError.customData + +Details about the MultiFactorError. + +Signature: + +```typescript +readonly customData: AuthError['customData'] & { + readonly operationType: typeof OperationTypeMap[keyof typeof OperationTypeMap]; + }; +``` + +### Example + + +```javascript +let resolver; +let multiFactorHints; + +signInWithEmailAndPassword(auth, email, password) + .then((result) => { + // User signed in. No 2nd factor challenge is needed. + }) + .catch((error) => { + if (error.code == 'auth/multi-factor-auth-required') { + resolver = getMultiFactorResolver(auth, error); + multiFactorHints = resolver.hints; + } else { + // Handle other errors. + } + }); + +// Obtain a multiFactorAssertion by verifying the second factor. + +const userCredential = await resolver.resolveSignIn(multiFactorAssertion); + +``` + diff --git a/docs-devsite/auth.multifactorinfo.md b/docs-devsite/auth.multifactorinfo.md new file mode 100644 index 00000000000..80a56164b9a --- /dev/null +++ b/docs-devsite/auth.multifactorinfo.md @@ -0,0 +1,68 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# MultiFactorInfo interface +A structure containing the information of a second factor entity. + +Signature: + +```typescript +export interface MultiFactorInfo +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [displayName](./auth.multifactorinfo.md#multifactorinfodisplayname) | string \| null | The user friendly name of the current second factor. | +| [enrollmentTime](./auth.multifactorinfo.md#multifactorinfoenrollmenttime) | string | The enrollment date of the second factor formatted as a UTC string. | +| [factorId](./auth.multifactorinfo.md#multifactorinfofactorid) | typeof [FactorIdMap](./auth.md#factorid)\[keyof typeof [FactorIdMap](./auth.md#factorid)\] | The identifier of the second factor. | +| [uid](./auth.multifactorinfo.md#multifactorinfouid) | string | The multi-factor enrollment ID. | + +## MultiFactorInfo.displayName + +The user friendly name of the current second factor. + +Signature: + +```typescript +readonly displayName?: string | null; +``` + +## MultiFactorInfo.enrollmentTime + +The enrollment date of the second factor formatted as a UTC string. + +Signature: + +```typescript +readonly enrollmentTime: string; +``` + +## MultiFactorInfo.factorId + +The identifier of the second factor. + +Signature: + +```typescript +readonly factorId: typeof FactorIdMap[keyof typeof FactorIdMap]; +``` + +## MultiFactorInfo.uid + +The multi-factor enrollment ID. + +Signature: + +```typescript +readonly uid: string; +``` diff --git a/docs-devsite/auth.multifactorresolver.md b/docs-devsite/auth.multifactorresolver.md new file mode 100644 index 00000000000..9d6bc3ebcda --- /dev/null +++ b/docs-devsite/auth.multifactorresolver.md @@ -0,0 +1,128 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# MultiFactorResolver interface +The class used to facilitate recovery from [MultiFactorError](./auth.multifactorerror.md#multifactorerror_interface) when a user needs to provide a second factor to sign in. + +Signature: + +```typescript +export interface MultiFactorResolver +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [hints](./auth.multifactorresolver.md#multifactorresolverhints) | [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface)\[\] | The list of hints for the second factors needed to complete the sign-in for the current session. | +| [session](./auth.multifactorresolver.md#multifactorresolversession) | [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) | The session identifier for the current sign-in flow, which can be used to complete the second factor sign-in. | + +## Methods + +| Method | Description | +| --- | --- | +| [resolveSignIn(assertion)](./auth.multifactorresolver.md#multifactorresolverresolvesignin) | A helper function to help users complete sign in with a second factor using an [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) confirming the user successfully completed the second factor challenge. | + +## MultiFactorResolver.hints + +The list of hints for the second factors needed to complete the sign-in for the current session. + +Signature: + +```typescript +readonly hints: MultiFactorInfo[]; +``` + +## MultiFactorResolver.session + +The session identifier for the current sign-in flow, which can be used to complete the second factor sign-in. + +Signature: + +```typescript +readonly session: MultiFactorSession; +``` + +## MultiFactorResolver.resolveSignIn() + +A helper function to help users complete sign in with a second factor using an [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) confirming the user successfully completed the second factor challenge. + +Signature: + +```typescript +resolveSignIn(assertion: MultiFactorAssertion): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| assertion | [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) | The multi-factor assertion to resolve sign-in with. | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> + +The promise that resolves with the user credential object. + +### Example + + +```javascript +const phoneAuthCredential = PhoneAuthProvider.credential(verificationId, verificationCode); +const multiFactorAssertion = PhoneMultiFactorGenerator.assertion(phoneAuthCredential); +const userCredential = await resolver.resolveSignIn(multiFactorAssertion); + +``` + +### Example + + +```javascript +let resolver; +let multiFactorHints; + +signInWithEmailAndPassword(auth, email, password) + .then((result) => { + // User signed in. No 2nd factor challenge is needed. + }) + .catch((error) => { + if (error.code == 'auth/multi-factor-auth-required') { + resolver = getMultiFactorResolver(auth, error); + // Show UI to let user select second factor. + multiFactorHints = resolver.hints; + } else { + // Handle other errors. + } + }); + +// The enrolled second factors that can be used to complete +// sign-in are returned in the `MultiFactorResolver.hints` list. +// UI needs to be presented to allow the user to select a second factor +// from that list. + +const selectedHint = // ; selected from multiFactorHints +const phoneAuthProvider = new PhoneAuthProvider(auth); +const phoneInfoOptions = { + multiFactorHint: selectedHint, + session: resolver.session +}; +const verificationId = phoneAuthProvider.verifyPhoneNumber(phoneInfoOptions, appVerifier); +// Store `verificationId` and show UI to let user enter verification code. + +// UI to enter verification code and continue. +// Continue button click handler +const phoneAuthCredential = PhoneAuthProvider.credential(verificationId, verificationCode); +const multiFactorAssertion = PhoneMultiFactorGenerator.assertion(phoneAuthCredential); +const userCredential = await resolver.resolveSignIn(multiFactorAssertion); + +``` + diff --git a/docs-devsite/auth.multifactorsession.md b/docs-devsite/auth.multifactorsession.md new file mode 100644 index 00000000000..9ad2d0a1682 --- /dev/null +++ b/docs-devsite/auth.multifactorsession.md @@ -0,0 +1,19 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# MultiFactorSession interface +An interface defining the multi-factor session object used for enrolling a second factor on a user or helping sign in an enrolled user with a second factor. + +Signature: + +```typescript +export interface MultiFactorSession +``` diff --git a/docs-devsite/auth.multifactoruser.md b/docs-devsite/auth.multifactoruser.md new file mode 100644 index 00000000000..9f25e4174fc --- /dev/null +++ b/docs-devsite/auth.multifactoruser.md @@ -0,0 +1,161 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# MultiFactorUser interface +An interface that defines the multi-factor related properties and operations pertaining to a [User](./auth.user.md#user_interface). + +Signature: + +```typescript +export interface MultiFactorUser +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [enrolledFactors](./auth.multifactoruser.md#multifactoruserenrolledfactors) | [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface)\[\] | Returns a list of the user's enrolled second factors. | + +## Methods + +| Method | Description | +| --- | --- | +| [enroll(assertion, displayName)](./auth.multifactoruser.md#multifactoruserenroll) | Enrolls a second factor as identified by the [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) for the user. | +| [getSession()](./auth.multifactoruser.md#multifactorusergetsession) | Returns the session identifier for a second factor enrollment operation. This is used to identify the user trying to enroll a second factor. | +| [unenroll(option)](./auth.multifactoruser.md#multifactoruserunenroll) | Unenrolls the specified second factor. | + +## MultiFactorUser.enrolledFactors + +Returns a list of the user's enrolled second factors. + +Signature: + +```typescript +readonly enrolledFactors: MultiFactorInfo[]; +``` + +## MultiFactorUser.enroll() + +Enrolls a second factor as identified by the [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) for the user. + +On resolution, the user tokens are updated to reflect the change in the JWT payload. Accepts an additional display name parameter used to identify the second factor to the end user. Recent re-authentication is required for this operation to succeed. On successful enrollment, existing Firebase sessions (refresh tokens) are revoked. When a new factor is enrolled, an email notification is sent to the user’s email. + +Signature: + +```typescript +enroll(assertion: MultiFactorAssertion, displayName?: string | null): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| assertion | [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) | The multi-factor assertion to enroll with. | +| displayName | string \| null | The display name of the second factor. | + +Returns: + +Promise<void> + +### Example + + +```javascript +const multiFactorUser = multiFactor(auth.currentUser); +const multiFactorSession = await multiFactorUser.getSession(); + +// Send verification code. +const phoneAuthProvider = new PhoneAuthProvider(auth); +const phoneInfoOptions = { + phoneNumber: phoneNumber, + session: multiFactorSession +}; +const verificationId = await phoneAuthProvider.verifyPhoneNumber(phoneInfoOptions, appVerifier); + +// Obtain verification code from user. +const phoneAuthCredential = PhoneAuthProvider.credential(verificationId, verificationCode); +const multiFactorAssertion = PhoneMultiFactorGenerator.assertion(phoneAuthCredential); +await multiFactorUser.enroll(multiFactorAssertion); +// Second factor enrolled. + +``` + +## MultiFactorUser.getSession() + +Returns the session identifier for a second factor enrollment operation. This is used to identify the user trying to enroll a second factor. + +Signature: + +```typescript +getSession(): Promise; +``` +Returns: + +Promise<[MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface)> + +The promise that resolves with the [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface). + +### Example + + +```javascript +const multiFactorUser = multiFactor(auth.currentUser); +const multiFactorSession = await multiFactorUser.getSession(); + +// Send verification code. +const phoneAuthProvider = new PhoneAuthProvider(auth); +const phoneInfoOptions = { + phoneNumber: phoneNumber, + session: multiFactorSession +}; +const verificationId = await phoneAuthProvider.verifyPhoneNumber(phoneInfoOptions, appVerifier); + +// Obtain verification code from user. +const phoneAuthCredential = PhoneAuthProvider.credential(verificationId, verificationCode); +const multiFactorAssertion = PhoneMultiFactorGenerator.assertion(phoneAuthCredential); +await multiFactorUser.enroll(multiFactorAssertion); + +``` + +## MultiFactorUser.unenroll() + +Unenrolls the specified second factor. + +To specify the factor to remove, pass a [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) object (retrieved from [MultiFactorUser.enrolledFactors](./auth.multifactoruser.md#multifactoruserenrolledfactors)) or the factor's UID string. Sessions are not revoked when the account is unenrolled. An email notification is likely to be sent to the user notifying them of the change. Recent re-authentication is required for this operation to succeed. When an existing factor is unenrolled, an email notification is sent to the user’s email. + +Signature: + +```typescript +unenroll(option: MultiFactorInfo | string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| option | [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) \| string | The multi-factor option to unenroll. | + +Returns: + +Promise<void> + +- A `Promise` which resolves when the unenroll operation is complete. + +### Example + + +```javascript +const multiFactorUser = multiFactor(auth.currentUser); +// Present user the option to choose which factor to unenroll. +await multiFactorUser.unenroll(multiFactorUser.enrolledFactors[i]) + +``` + diff --git a/docs-devsite/auth.oauthcredential.md b/docs-devsite/auth.oauthcredential.md new file mode 100644 index 00000000000..dc3855e01a1 --- /dev/null +++ b/docs-devsite/auth.oauthcredential.md @@ -0,0 +1,105 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# OAuthCredential class +Represents the OAuth credentials returned by an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). + +Implementations specify the details about each auth provider's credential requirements. + +Signature: + +```typescript +export declare class OAuthCredential extends AuthCredential +``` +Extends: [AuthCredential](./auth.authcredential.md#authcredential_class) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [accessToken](./auth.oauthcredential.md#oauthcredentialaccesstoken) | | string | The OAuth access token associated with the credential if it belongs to an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class), such as facebook.com, twitter.com, etc. | +| [idToken](./auth.oauthcredential.md#oauthcredentialidtoken) | | string | The OAuth ID token associated with the credential if it belongs to an OIDC provider, such as google.com. | +| [secret](./auth.oauthcredential.md#oauthcredentialsecret) | | string | The OAuth access token secret associated with the credential if it belongs to an OAuth 1.0 provider, such as twitter.com. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [fromJSON(json)](./auth.oauthcredential.md#oauthcredentialfromjson) | static | Static method to deserialize a JSON representation of an object into an [AuthCredential](./auth.authcredential.md#authcredential_class). | +| [toJSON()](./auth.oauthcredential.md#oauthcredentialtojson) | | Returns a JSON-serializable representation of this object. | + +## OAuthCredential.accessToken + +The OAuth access token associated with the credential if it belongs to an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class), such as `facebook.com`, `twitter.com`, etc. + +Signature: + +```typescript +accessToken?: string; +``` + +## OAuthCredential.idToken + +The OAuth ID token associated with the credential if it belongs to an OIDC provider, such as `google.com`. + +Signature: + +```typescript +idToken?: string; +``` + +## OAuthCredential.secret + +The OAuth access token secret associated with the credential if it belongs to an OAuth 1.0 provider, such as `twitter.com`. + +Signature: + +```typescript +secret?: string; +``` + +## OAuthCredential.fromJSON() + +Static method to deserialize a JSON representation of an object into an [AuthCredential](./auth.authcredential.md#authcredential_class). + +Signature: + +```typescript +static fromJSON(json: string | object): OAuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| json | string \| object | Input can be either Object or the stringified representation of the object. When string is provided, JSON.parse would be called first. | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null + +If the JSON input does not represent an [AuthCredential](./auth.authcredential.md#authcredential_class), null is returned. + +## OAuthCredential.toJSON() + +Returns a JSON-serializable representation of this object. + +Signature: + +```typescript +toJSON(): object; +``` +Returns: + +object + +a JSON-serializable representation of this object. + diff --git a/docs-devsite/auth.oauthcredentialoptions.md b/docs-devsite/auth.oauthcredentialoptions.md new file mode 100644 index 00000000000..0389c534c17 --- /dev/null +++ b/docs-devsite/auth.oauthcredentialoptions.md @@ -0,0 +1,61 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# OAuthCredentialOptions interface +Defines the options for initializing an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). + +For ID tokens with nonce claim, the raw nonce has to also be provided. + +Signature: + +```typescript +export interface OAuthCredentialOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [accessToken](./auth.oauthcredentialoptions.md#oauthcredentialoptionsaccesstoken) | string | The OAuth access token used to initialize the [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). | +| [idToken](./auth.oauthcredentialoptions.md#oauthcredentialoptionsidtoken) | string | The OAuth ID token used to initialize the [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). | +| [rawNonce](./auth.oauthcredentialoptions.md#oauthcredentialoptionsrawnonce) | string | The raw nonce associated with the ID token. | + +## OAuthCredentialOptions.accessToken + +The OAuth access token used to initialize the [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). + +Signature: + +```typescript +accessToken?: string; +``` + +## OAuthCredentialOptions.idToken + +The OAuth ID token used to initialize the [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). + +Signature: + +```typescript +idToken?: string; +``` + +## OAuthCredentialOptions.rawNonce + +The raw nonce associated with the ID token. + +It is required when an ID token with a nonce field is provided. The SHA-256 hash of the raw nonce must match the nonce field in the ID token. + +Signature: + +```typescript +rawNonce?: string; +``` diff --git a/docs-devsite/auth.oauthprovider.md b/docs-devsite/auth.oauthprovider.md new file mode 100644 index 00000000000..30141fcce40 --- /dev/null +++ b/docs-devsite/auth.oauthprovider.md @@ -0,0 +1,168 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# OAuthProvider class +Provider for generating generic [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). + +Signature: + +```typescript +export declare class OAuthProvider extends BaseOAuthProvider +``` +Extends: BaseOAuthProvider + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [credential(params)](./auth.oauthprovider.md#oauthprovidercredential) | | Creates a [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a generic OAuth provider's access token or ID token. | +| [credentialFromError(error)](./auth.oauthprovider.md#oauthprovidercredentialfromerror) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. | +| [credentialFromJSON(json)](./auth.oauthprovider.md#oauthprovidercredentialfromjson) | static | Creates an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a JSON string or a plain object. | +| [credentialFromResult(userCredential)](./auth.oauthprovider.md#oauthprovidercredentialfromresult) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). | + +## OAuthProvider.credential() + +Creates a [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a generic OAuth provider's access token or ID token. + +The raw nonce is required when an ID token with a nonce field is provided. The SHA-256 hash of the raw nonce must match the nonce field in the ID token. + +Signature: + +```typescript +credential(params: OAuthCredentialOptions): OAuthCredential; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| params | [OAuthCredentialOptions](./auth.oauthcredentialoptions.md#oauthcredentialoptions_interface) | Either the options object containing the ID token, access token and raw nonce or the ID token string. | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) + +### Example + + +```javascript +// `googleUser` from the onsuccess Google Sign In callback. +// Initialize a generate OAuth provider with a `google.com` providerId. +const provider = new OAuthProvider('google.com'); +const credential = provider.credential({ + idToken: googleUser.getAuthResponse().id_token, +}); +const result = await signInWithCredential(credential); + +``` + +## OAuthProvider.credentialFromError() + +Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. + +Signature: + +```typescript +static credentialFromError(error: FirebaseError): OAuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null + +## OAuthProvider.credentialFromJSON() + +Creates an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a JSON string or a plain object. + +Signature: + +```typescript +static credentialFromJSON(json: object | string): OAuthCredential; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| json | object \| string | A plain object or a JSON string | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) + +## OAuthProvider.credentialFromResult() + +Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). + +Signature: + +```typescript +static credentialFromResult(userCredential: UserCredential): OAuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null + +### Example 1 + + +```javascript +// Sign in using a redirect. +const provider = new OAuthProvider('google.com'); +// Start a sign in process for an unauthenticated user. +provider.addScope('profile'); +provider.addScope('email'); +await signInWithRedirect(auth, provider); +// This will trigger a full page redirect away from your app + +// After returning from the redirect when your app initializes you can obtain the result +const result = await getRedirectResult(auth); +if (result) { + // This is the signed-in user + const user = result.user; + // This gives you a OAuth Access Token for the provider. + const credential = provider.credentialFromResult(auth, result); + const token = credential.accessToken; +} + +``` + +### Example 2 + + +```javascript +// Sign in using a popup. +const provider = new OAuthProvider('google.com'); +provider.addScope('profile'); +provider.addScope('email'); +const result = await signInWithPopup(auth, provider); + +// The signed-in user info. +const user = result.user; +// This gives you a OAuth Access Token for the provider. +const credential = provider.credentialFromResult(auth, result); +const token = credential.accessToken; + +``` + diff --git a/docs-devsite/auth.parsedtoken.md b/docs-devsite/auth.parsedtoken.md new file mode 100644 index 00000000000..7892b135536 --- /dev/null +++ b/docs-devsite/auth.parsedtoken.md @@ -0,0 +1,83 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ParsedToken interface +Interface representing a parsed ID token. + +Signature: + +```typescript +export interface ParsedToken +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [auth\_time](./auth.parsedtoken.md#parsedtokenauth_time) | string | Time at which authentication was performed. | +| [exp](./auth.parsedtoken.md#parsedtokenexp) | string | Expiration time of the token. | +| [firebase](./auth.parsedtoken.md#parsedtokenfirebase) | { 'sign\_in\_provider'?: string; 'sign\_in\_second\_factor'?: string; 'identities'?: Record<string, string>; } | Firebase specific claims, containing the provider(s) used to authenticate the user. | +| [iat](./auth.parsedtoken.md#parsedtokeniat) | string | Issuance time of the token. | +| [sub](./auth.parsedtoken.md#parsedtokensub) | string | UID of the user. | + +## ParsedToken.auth\_time + +Time at which authentication was performed. + +Signature: + +```typescript +'auth_time'?: string; +``` + +## ParsedToken.exp + +Expiration time of the token. + +Signature: + +```typescript +'exp'?: string; +``` + +## ParsedToken.firebase + +Firebase specific claims, containing the provider(s) used to authenticate the user. + +Signature: + +```typescript +'firebase'?: { + 'sign_in_provider'?: string; + 'sign_in_second_factor'?: string; + 'identities'?: Record; + }; +``` + +## ParsedToken.iat + +Issuance time of the token. + +Signature: + +```typescript +'iat'?: string; +``` + +## ParsedToken.sub + +UID of the user. + +Signature: + +```typescript +'sub'?: string; +``` diff --git a/docs-devsite/auth.persistence.md b/docs-devsite/auth.persistence.md new file mode 100644 index 00000000000..b3f9ecb11e1 --- /dev/null +++ b/docs-devsite/auth.persistence.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Persistence interface +An interface covering the possible persistence mechanism types. + +Signature: + +```typescript +export interface Persistence +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [type](./auth.persistence.md#persistencetype) | 'SESSION' \| 'LOCAL' \| 'NONE' | Type of Persistence. - 'SESSION' is used for temporary persistence such as sessionStorage. - 'LOCAL' is used for long term persistence such as localStorage or IndexedDB. - 'NONE' is used for in-memory, or no persistence. | + +## Persistence.type + +Type of Persistence. - 'SESSION' is used for temporary persistence such as `sessionStorage`. - 'LOCAL' is used for long term persistence such as `localStorage` or `IndexedDB`. - 'NONE' is used for in-memory, or no persistence. + +Signature: + +```typescript +readonly type: 'SESSION' | 'LOCAL' | 'NONE'; +``` diff --git a/docs-devsite/auth.phoneauthcredential.md b/docs-devsite/auth.phoneauthcredential.md new file mode 100644 index 00000000000..44a85db5254 --- /dev/null +++ b/docs-devsite/auth.phoneauthcredential.md @@ -0,0 +1,63 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# PhoneAuthCredential class +Represents the credentials returned by [PhoneAuthProvider](./auth.phoneauthprovider.md#phoneauthprovider_class). + +Signature: + +```typescript +export declare class PhoneAuthCredential extends AuthCredential +``` +Extends: [AuthCredential](./auth.authcredential.md#authcredential_class) + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [fromJSON(json)](./auth.phoneauthcredential.md#phoneauthcredentialfromjson) | static | Generates a phone credential based on a plain object or a JSON string. | +| [toJSON()](./auth.phoneauthcredential.md#phoneauthcredentialtojson) | | Returns a JSON-serializable representation of this object. | + +## PhoneAuthCredential.fromJSON() + +Generates a phone credential based on a plain object or a JSON string. + +Signature: + +```typescript +static fromJSON(json: object | string): PhoneAuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| json | object \| string | | + +Returns: + +[PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class) \| null + +## PhoneAuthCredential.toJSON() + +Returns a JSON-serializable representation of this object. + +Signature: + +```typescript +toJSON(): object; +``` +Returns: + +object + +a JSON-serializable representation of this object. + diff --git a/docs-devsite/auth.phoneauthprovider.md b/docs-devsite/auth.phoneauthprovider.md new file mode 100644 index 00000000000..41e743386de --- /dev/null +++ b/docs-devsite/auth.phoneauthprovider.md @@ -0,0 +1,256 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# PhoneAuthProvider class +Provider for generating an [PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class). + +Signature: + +```typescript +export declare class PhoneAuthProvider +``` + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(auth)](./auth.phoneauthprovider.md#phoneauthproviderconstructor) | | Constructs a new instance of the PhoneAuthProvider class | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [PHONE\_SIGN\_IN\_METHOD](./auth.phoneauthprovider.md#phoneauthproviderphone_sign_in_method) | static | 'phone' | Always set to [SignInMethod](./auth.md#signinmethod).PHONE. | +| [PROVIDER\_ID](./auth.phoneauthprovider.md#phoneauthproviderprovider_id) | static | 'phone' | Always set to [ProviderId](./auth.md#providerid).PHONE. | +| [providerId](./auth.phoneauthprovider.md#phoneauthproviderproviderid) | | "phone" | Always set to [ProviderId](./auth.md#providerid).PHONE. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [credential(verificationId, verificationCode)](./auth.phoneauthprovider.md#phoneauthprovidercredential) | static | Creates a phone auth credential, given the verification ID from [PhoneAuthProvider.verifyPhoneNumber()](./auth.phoneauthprovider.md#phoneauthproviderverifyphonenumber) and the code that was sent to the user's mobile device. | +| [credentialFromError(error)](./auth.phoneauthprovider.md#phoneauthprovidercredentialfromerror) | static | Returns an [AuthCredential](./auth.authcredential.md#authcredential_class) when passed an error. | +| [credentialFromResult(userCredential)](./auth.phoneauthprovider.md#phoneauthprovidercredentialfromresult) | static | Generates an [AuthCredential](./auth.authcredential.md#authcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). | +| [verifyPhoneNumber(phoneOptions, applicationVerifier)](./auth.phoneauthprovider.md#phoneauthproviderverifyphonenumber) | | Starts a phone number authentication flow by sending a verification code to the given phone number. | + +## PhoneAuthProvider.(constructor) + +Constructs a new instance of the `PhoneAuthProvider` class + +Signature: + +```typescript +constructor(auth: Auth); +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The Firebase [Auth](./auth.auth.md#auth_interface) instance in which sign-ins should occur. | + +## PhoneAuthProvider.PHONE\_SIGN\_IN\_METHOD + +Always set to [SignInMethod](./auth.md#signinmethod).PHONE. + +Signature: + +```typescript +static readonly PHONE_SIGN_IN_METHOD: 'phone'; +``` + +## PhoneAuthProvider.PROVIDER\_ID + +Always set to [ProviderId](./auth.md#providerid).PHONE. + +Signature: + +```typescript +static readonly PROVIDER_ID: 'phone'; +``` + +## PhoneAuthProvider.providerId + +Always set to [ProviderId](./auth.md#providerid).PHONE. + +Signature: + +```typescript +readonly providerId: "phone"; +``` + +## PhoneAuthProvider.credential() + +Creates a phone auth credential, given the verification ID from [PhoneAuthProvider.verifyPhoneNumber()](./auth.phoneauthprovider.md#phoneauthproviderverifyphonenumber) and the code that was sent to the user's mobile device. + +Signature: + +```typescript +static credential(verificationId: string, verificationCode: string): PhoneAuthCredential; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| verificationId | string | The verification ID returned from [PhoneAuthProvider.verifyPhoneNumber()](./auth.phoneauthprovider.md#phoneauthproviderverifyphonenumber). | +| verificationCode | string | The verification code sent to the user's mobile device. | + +Returns: + +[PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class) + +The auth provider credential. + +### Example 1 + + +```javascript +const provider = new PhoneAuthProvider(auth); +const verificationId = provider.verifyPhoneNumber(phoneNumber, applicationVerifier); +// Obtain verificationCode from the user. +const authCredential = PhoneAuthProvider.credential(verificationId, verificationCode); +const userCredential = signInWithCredential(auth, authCredential); + +``` + +### Example 2 + +An alternative flow is provided using the `signInWithPhoneNumber` method. + +```javascript +const confirmationResult = await signInWithPhoneNumber(auth, phoneNumber, applicationVerifier); +// Obtain verificationCode from the user. +const userCredential = await confirmationResult.confirm(verificationCode); + +``` + +## PhoneAuthProvider.credentialFromError() + +Returns an [AuthCredential](./auth.authcredential.md#authcredential_class) when passed an error. + +This method works for errors like `auth/account-exists-with-different-credentials`. This is useful for recovering when attempting to set a user's phone number but the number in question is already tied to another account. For example, the following code tries to update the current user's phone number, and if that fails, links the user with the account associated with that number: + +```js +const provider = new PhoneAuthProvider(auth); +const verificationId = await provider.verifyPhoneNumber(number, verifier); +try { + const code = ''; // Prompt the user for the verification code + await updatePhoneNumber( + auth.currentUser, + PhoneAuthProvider.credential(verificationId, code)); +} catch (e) { + if ((e as FirebaseError)?.code === 'auth/account-exists-with-different-credential') { + const cred = PhoneAuthProvider.credentialFromError(e); + await linkWithCredential(auth.currentUser, cred); + } +} + +// At this point, auth.currentUser.phoneNumber === number. + +``` + +Signature: + +```typescript +static credentialFromError(error: FirebaseError): AuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | The error to generate a credential from. | + +Returns: + +[AuthCredential](./auth.authcredential.md#authcredential_class) \| null + +## PhoneAuthProvider.credentialFromResult() + +Generates an [AuthCredential](./auth.authcredential.md#authcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). + +Signature: + +```typescript +static credentialFromResult(userCredential: UserCredential): AuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | + +Returns: + +[AuthCredential](./auth.authcredential.md#authcredential_class) \| null + +## PhoneAuthProvider.verifyPhoneNumber() + +Starts a phone number authentication flow by sending a verification code to the given phone number. + +Signature: + +```typescript +verifyPhoneNumber(phoneOptions: PhoneInfoOptions | string, applicationVerifier: ApplicationVerifier): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| phoneOptions | [PhoneInfoOptions](./auth.md#phoneinfooptions) \| string | | +| applicationVerifier | [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) | For abuse prevention, this method also requires a [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface). This SDK includes a reCAPTCHA-based implementation, [RecaptchaVerifier](./auth.recaptchaverifier.md#recaptchaverifier_class). | + +Returns: + +Promise<string> + +A Promise for a verification ID that can be passed to [PhoneAuthProvider.credential()](./auth.phoneauthprovider.md#phoneauthprovidercredential) to identify this flow.. + +### Example 1 + + +```javascript +const provider = new PhoneAuthProvider(auth); +const verificationId = await provider.verifyPhoneNumber(phoneNumber, applicationVerifier); +// Obtain verificationCode from the user. +const authCredential = PhoneAuthProvider.credential(verificationId, verificationCode); +const userCredential = await signInWithCredential(auth, authCredential); + +``` + +### Example 2 + +An alternative flow is provided using the `signInWithPhoneNumber` method. + +```javascript +const confirmationResult = signInWithPhoneNumber(auth, phoneNumber, applicationVerifier); +// Obtain verificationCode from the user. +const userCredential = confirmationResult.confirm(verificationCode); + +``` + +### Example + + +```javascript +// 'recaptcha-container' is the ID of an element in the DOM. +const applicationVerifier = new RecaptchaVerifier('recaptcha-container'); +const provider = new PhoneAuthProvider(auth); +const verificationId = await provider.verifyPhoneNumber('+16505550101', applicationVerifier); +// Obtain the verificationCode from the user. +const phoneCredential = PhoneAuthProvider.credential(verificationId, verificationCode); +const userCredential = await signInWithCredential(auth, phoneCredential); + +``` + diff --git a/docs-devsite/auth.phonemultifactorassertion.md b/docs-devsite/auth.phonemultifactorassertion.md new file mode 100644 index 00000000000..1f6afd2410f --- /dev/null +++ b/docs-devsite/auth.phonemultifactorassertion.md @@ -0,0 +1,21 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# PhoneMultiFactorAssertion interface +The class for asserting ownership of a phone second factor. Provided by [PhoneMultiFactorGenerator.assertion()](./auth.phonemultifactorgenerator.md#phonemultifactorgeneratorassertion). + +Signature: + +```typescript +export interface PhoneMultiFactorAssertion extends MultiFactorAssertion +``` +Extends: [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) + diff --git a/docs-devsite/auth.phonemultifactorenrollinfooptions.md b/docs-devsite/auth.phonemultifactorenrollinfooptions.md new file mode 100644 index 00000000000..f36cfc29d8d --- /dev/null +++ b/docs-devsite/auth.phonemultifactorenrollinfooptions.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# PhoneMultiFactorEnrollInfoOptions interface +Options used for enrolling a second factor. + +Signature: + +```typescript +export interface PhoneMultiFactorEnrollInfoOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [phoneNumber](./auth.phonemultifactorenrollinfooptions.md#phonemultifactorenrollinfooptionsphonenumber) | string | Phone number to send a verification code to. | +| [session](./auth.phonemultifactorenrollinfooptions.md#phonemultifactorenrollinfooptionssession) | [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) | The [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) obtained via [MultiFactorUser.getSession()](./auth.multifactoruser.md#multifactorusergetsession). | + +## PhoneMultiFactorEnrollInfoOptions.phoneNumber + +Phone number to send a verification code to. + +Signature: + +```typescript +phoneNumber: string; +``` + +## PhoneMultiFactorEnrollInfoOptions.session + +The [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) obtained via [MultiFactorUser.getSession()](./auth.multifactoruser.md#multifactorusergetsession). + +Signature: + +```typescript +session: MultiFactorSession; +``` diff --git a/docs-devsite/auth.phonemultifactorgenerator.md b/docs-devsite/auth.phonemultifactorgenerator.md new file mode 100644 index 00000000000..a59d34814bf --- /dev/null +++ b/docs-devsite/auth.phonemultifactorgenerator.md @@ -0,0 +1,64 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# PhoneMultiFactorGenerator class +Provider for generating a [PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface). + +Signature: + +```typescript +export declare class PhoneMultiFactorGenerator +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [FACTOR\_ID](./auth.phonemultifactorgenerator.md#phonemultifactorgeneratorfactor_id) | static | string | The identifier of the phone second factor: phone. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [assertion(credential)](./auth.phonemultifactorgenerator.md#phonemultifactorgeneratorassertion) | static | Provides a [PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface) to confirm ownership of the phone second factor. | + +## PhoneMultiFactorGenerator.FACTOR\_ID + +The identifier of the phone second factor: `phone`. + +Signature: + +```typescript +static FACTOR_ID: string; +``` + +## PhoneMultiFactorGenerator.assertion() + +Provides a [PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface) to confirm ownership of the phone second factor. + +Signature: + +```typescript +static assertion(credential: PhoneAuthCredential): PhoneMultiFactorAssertion; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| credential | [PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class) | | + +Returns: + +[PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface) + +A [PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface) which can be used with [MultiFactorResolver.resolveSignIn()](./auth.multifactorresolver.md#multifactorresolverresolvesignin) + diff --git a/docs-devsite/auth.phonemultifactorinfo.md b/docs-devsite/auth.phonemultifactorinfo.md new file mode 100644 index 00000000000..c12c72b8a55 --- /dev/null +++ b/docs-devsite/auth.phonemultifactorinfo.md @@ -0,0 +1,36 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# PhoneMultiFactorInfo interface +The subclass of the [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) interface for phone number second factors. The `factorId` of this second factor is [FactorId](./auth.md#factorid).PHONE. + +Signature: + +```typescript +export interface PhoneMultiFactorInfo extends MultiFactorInfo +``` +Extends: [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [phoneNumber](./auth.phonemultifactorinfo.md#phonemultifactorinfophonenumber) | string | The phone number associated with the current second factor. | + +## PhoneMultiFactorInfo.phoneNumber + +The phone number associated with the current second factor. + +Signature: + +```typescript +readonly phoneNumber: string; +``` diff --git a/docs-devsite/auth.phonemultifactorsignininfooptions.md b/docs-devsite/auth.phonemultifactorsignininfooptions.md new file mode 100644 index 00000000000..592ef7118b3 --- /dev/null +++ b/docs-devsite/auth.phonemultifactorsignininfooptions.md @@ -0,0 +1,61 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# PhoneMultiFactorSignInInfoOptions interface +Options used for signing in with a second factor. + +Signature: + +```typescript +export interface PhoneMultiFactorSignInInfoOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [multiFactorHint](./auth.phonemultifactorsignininfooptions.md#phonemultifactorsignininfooptionsmultifactorhint) | [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) | The [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) obtained via [MultiFactorResolver.hints](./auth.multifactorresolver.md#multifactorresolverhints).One of multiFactorHint or multiFactorUid is required. | +| [multiFactorUid](./auth.phonemultifactorsignininfooptions.md#phonemultifactorsignininfooptionsmultifactoruid) | string | The uid of the second factor.One of multiFactorHint or multiFactorUid is required. | +| [session](./auth.phonemultifactorsignininfooptions.md#phonemultifactorsignininfooptionssession) | [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) | The [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) obtained via [MultiFactorResolver.session](./auth.multifactorresolver.md#multifactorresolversession). | + +## PhoneMultiFactorSignInInfoOptions.multiFactorHint + +The [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) obtained via [MultiFactorResolver.hints](./auth.multifactorresolver.md#multifactorresolverhints). + +One of `multiFactorHint` or `multiFactorUid` is required. + +Signature: + +```typescript +multiFactorHint?: MultiFactorInfo; +``` + +## PhoneMultiFactorSignInInfoOptions.multiFactorUid + +The uid of the second factor. + +One of `multiFactorHint` or `multiFactorUid` is required. + +Signature: + +```typescript +multiFactorUid?: string; +``` + +## PhoneMultiFactorSignInInfoOptions.session + +The [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) obtained via [MultiFactorResolver.session](./auth.multifactorresolver.md#multifactorresolversession). + +Signature: + +```typescript +session: MultiFactorSession; +``` diff --git a/docs-devsite/auth.phonesinglefactorinfooptions.md b/docs-devsite/auth.phonesinglefactorinfooptions.md new file mode 100644 index 00000000000..f7846d0db42 --- /dev/null +++ b/docs-devsite/auth.phonesinglefactorinfooptions.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# PhoneSingleFactorInfoOptions interface +Options used for single-factor sign-in. + +Signature: + +```typescript +export interface PhoneSingleFactorInfoOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [phoneNumber](./auth.phonesinglefactorinfooptions.md#phonesinglefactorinfooptionsphonenumber) | string | Phone number to send a verification code to. | + +## PhoneSingleFactorInfoOptions.phoneNumber + +Phone number to send a verification code to. + +Signature: + +```typescript +phoneNumber: string; +``` diff --git a/docs-devsite/auth.popupredirectresolver.md b/docs-devsite/auth.popupredirectresolver.md new file mode 100644 index 00000000000..67c3274847c --- /dev/null +++ b/docs-devsite/auth.popupredirectresolver.md @@ -0,0 +1,19 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# PopupRedirectResolver interface +A resolver used for handling DOM specific operations like [signInWithPopup()](./auth.md#signinwithpopup) or [signInWithRedirect()](./auth.md#signinwithredirect). + +Signature: + +```typescript +export interface PopupRedirectResolver +``` diff --git a/docs-devsite/auth.reactnativeasyncstorage.md b/docs-devsite/auth.reactnativeasyncstorage.md new file mode 100644 index 00000000000..231e7d2ed31 --- /dev/null +++ b/docs-devsite/auth.reactnativeasyncstorage.md @@ -0,0 +1,89 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ReactNativeAsyncStorage interface +Interface for a supplied `AsyncStorage`. + +Signature: + +```typescript +export interface ReactNativeAsyncStorage +``` + +## Methods + +| Method | Description | +| --- | --- | +| [getItem(key)](./auth.reactnativeasyncstorage.md#reactnativeasyncstoragegetitem) | Retrieve an item from storage. | +| [removeItem(key)](./auth.reactnativeasyncstorage.md#reactnativeasyncstorageremoveitem) | Remove an item from storage. | +| [setItem(key, value)](./auth.reactnativeasyncstorage.md#reactnativeasyncstoragesetitem) | Persist an item in storage. | + +## ReactNativeAsyncStorage.getItem() + +Retrieve an item from storage. + +Signature: + +```typescript +getItem(key: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| key | string | storage key. | + +Returns: + +Promise<string \| null> + +## ReactNativeAsyncStorage.removeItem() + +Remove an item from storage. + +Signature: + +```typescript +removeItem(key: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| key | string | storage key. | + +Returns: + +Promise<void> + +## ReactNativeAsyncStorage.setItem() + +Persist an item in storage. + +Signature: + +```typescript +setItem(key: string, value: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| key | string | storage key. | +| value | string | storage value. | + +Returns: + +Promise<void> + diff --git a/docs-devsite/auth.recaptchaparameters.md b/docs-devsite/auth.recaptchaparameters.md new file mode 100644 index 00000000000..5d70f1826eb --- /dev/null +++ b/docs-devsite/auth.recaptchaparameters.md @@ -0,0 +1,23 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# RecaptchaParameters interface +Interface representing reCAPTCHA parameters. + +See the \[reCAPTCHA docs\](https://developers.google.com/recaptcha/docs/display\#render\_param) for the list of accepted parameters. All parameters are accepted except for `sitekey`: Firebase Auth provisions a reCAPTCHA for each project and will configure the site key upon rendering. + +For an invisible reCAPTCHA, set the `size` key to `invisible`. + +Signature: + +```typescript +export interface RecaptchaParameters +``` diff --git a/docs-devsite/auth.recaptchaverifier.md b/docs-devsite/auth.recaptchaverifier.md new file mode 100644 index 00000000000..4f32d489aed --- /dev/null +++ b/docs-devsite/auth.recaptchaverifier.md @@ -0,0 +1,116 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# RecaptchaVerifier class +An [reCAPTCHA](https://www.google.com/recaptcha/)-based application verifier. + +Signature: + +```typescript +export declare class RecaptchaVerifier implements ApplicationVerifierInternal +``` +Implements: ApplicationVerifierInternal + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(containerOrId, parameters, authExtern)](./auth.recaptchaverifier.md#recaptchaverifierconstructor) | | Constructs a new instance of the RecaptchaVerifier class | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./auth.recaptchaverifier.md#recaptchaverifiertype) | | (not declared) | The application verifier type. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [clear()](./auth.recaptchaverifier.md#recaptchaverifierclear) | | Clears the reCAPTCHA widget from the page and destroys the instance. | +| [render()](./auth.recaptchaverifier.md#recaptchaverifierrender) | | Renders the reCAPTCHA widget on the page. | +| [verify()](./auth.recaptchaverifier.md#recaptchaverifierverify) | | Waits for the user to solve the reCAPTCHA and resolves with the reCAPTCHA token. | + +## RecaptchaVerifier.(constructor) + +Constructs a new instance of the `RecaptchaVerifier` class + +Check the reCAPTCHA docs for a comprehensive list. All parameters are accepted except for the sitekey. Firebase Auth backend provisions a reCAPTCHA for each project and will configure this upon rendering. For an invisible reCAPTCHA, a size key must have the value 'invisible'. + +Signature: + +```typescript +constructor(containerOrId: HTMLElement | string, parameters: RecaptchaParameters, authExtern: Auth); +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| containerOrId | HTMLElement \| string | The reCAPTCHA container parameter. | +| parameters | [RecaptchaParameters](./auth.recaptchaparameters.md#recaptchaparameters_interface) | The optional reCAPTCHA parameters. | +| authExtern | [Auth](./auth.auth.md#auth_interface) | The corresponding Firebase [Auth](./auth.auth.md#auth_interface) instance. | + +## RecaptchaVerifier.type + +The application verifier type. + +For a reCAPTCHA verifier, this is 'recaptcha'. + +Signature: + +```typescript +readonly type = "recaptcha"; +``` + +## RecaptchaVerifier.clear() + +Clears the reCAPTCHA widget from the page and destroys the instance. + +Signature: + +```typescript +clear(): void; +``` +Returns: + +void + +## RecaptchaVerifier.render() + +Renders the reCAPTCHA widget on the page. + +Signature: + +```typescript +render(): Promise; +``` +Returns: + +Promise<number> + +A Promise that resolves with the reCAPTCHA widget ID. + +## RecaptchaVerifier.verify() + +Waits for the user to solve the reCAPTCHA and resolves with the reCAPTCHA token. + +Signature: + +```typescript +verify(): Promise; +``` +Returns: + +Promise<string> + +A Promise for the reCAPTCHA token. + diff --git a/docs-devsite/auth.samlauthprovider.md b/docs-devsite/auth.samlauthprovider.md new file mode 100644 index 00000000000..d25dd1999ed --- /dev/null +++ b/docs-devsite/auth.samlauthprovider.md @@ -0,0 +1,119 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# SAMLAuthProvider class +An [AuthProvider](./auth.authprovider.md#authprovider_interface) for SAML. + +Signature: + +```typescript +export declare class SAMLAuthProvider extends FederatedAuthProvider +``` +Extends: FederatedAuthProvider + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(providerId)](./auth.samlauthprovider.md#samlauthproviderconstructor) | | Constructor. The providerId must start with "saml." | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [credentialFromError(error)](./auth.samlauthprovider.md#samlauthprovidercredentialfromerror) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. | +| [credentialFromJSON(json)](./auth.samlauthprovider.md#samlauthprovidercredentialfromjson) | static | Creates an [AuthCredential](./auth.authcredential.md#authcredential_class) from a JSON string or a plain object. | +| [credentialFromResult(userCredential)](./auth.samlauthprovider.md#samlauthprovidercredentialfromresult) | static | Generates an [AuthCredential](./auth.authcredential.md#authcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface) after a successful SAML flow completes. | + +## SAMLAuthProvider.(constructor) + +Constructor. The providerId must start with "saml." + +Signature: + +```typescript +constructor(providerId: string); +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| providerId | string | SAML provider ID. | + +## SAMLAuthProvider.credentialFromError() + +Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. + +Signature: + +```typescript +static credentialFromError(error: FirebaseError): AuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | | + +Returns: + +[AuthCredential](./auth.authcredential.md#authcredential_class) \| null + +## SAMLAuthProvider.credentialFromJSON() + +Creates an [AuthCredential](./auth.authcredential.md#authcredential_class) from a JSON string or a plain object. + +Signature: + +```typescript +static credentialFromJSON(json: string | object): AuthCredential; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| json | string \| object | A plain object or a JSON string | + +Returns: + +[AuthCredential](./auth.authcredential.md#authcredential_class) + +## SAMLAuthProvider.credentialFromResult() + +Generates an [AuthCredential](./auth.authcredential.md#authcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface) after a successful SAML flow completes. + +For example, to get an [AuthCredential](./auth.authcredential.md#authcredential_class), you could write the following code: + +```js +const userCredential = await signInWithPopup(auth, samlProvider); +const credential = SAMLAuthProvider.credentialFromResult(userCredential); + +``` + +Signature: + +```typescript +static credentialFromResult(userCredential: UserCredential): AuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | + +Returns: + +[AuthCredential](./auth.authcredential.md#authcredential_class) \| null + diff --git a/docs-devsite/auth.twitterauthprovider.md b/docs-devsite/auth.twitterauthprovider.md new file mode 100644 index 00000000000..9ae64b6bdaf --- /dev/null +++ b/docs-devsite/auth.twitterauthprovider.md @@ -0,0 +1,173 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# TwitterAuthProvider class +Provider for generating an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).TWITTER. + +Signature: + +```typescript +export declare class TwitterAuthProvider extends BaseOAuthProvider +``` +Extends: BaseOAuthProvider + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)()](./auth.twitterauthprovider.md#twitterauthproviderconstructor) | | Constructs a new instance of the TwitterAuthProvider class | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [PROVIDER\_ID](./auth.twitterauthprovider.md#twitterauthproviderprovider_id) | static | 'twitter.com' | Always set to [ProviderId](./auth.md#providerid).TWITTER. | +| [TWITTER\_SIGN\_IN\_METHOD](./auth.twitterauthprovider.md#twitterauthprovidertwitter_sign_in_method) | static | 'twitter.com' | Always set to [SignInMethod](./auth.md#signinmethod).TWITTER. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [credential(token, secret)](./auth.twitterauthprovider.md#twitterauthprovidercredential) | static | Creates a credential for Twitter. | +| [credentialFromError(error)](./auth.twitterauthprovider.md#twitterauthprovidercredentialfromerror) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. | +| [credentialFromResult(userCredential)](./auth.twitterauthprovider.md#twitterauthprovidercredentialfromresult) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). | + +## TwitterAuthProvider.(constructor) + +Constructs a new instance of the `TwitterAuthProvider` class + +Signature: + +```typescript +constructor(); +``` + +## TwitterAuthProvider.PROVIDER\_ID + +Always set to [ProviderId](./auth.md#providerid).TWITTER. + +Signature: + +```typescript +static readonly PROVIDER_ID: 'twitter.com'; +``` + +## TwitterAuthProvider.TWITTER\_SIGN\_IN\_METHOD + +Always set to [SignInMethod](./auth.md#signinmethod).TWITTER. + +Signature: + +```typescript +static readonly TWITTER_SIGN_IN_METHOD: 'twitter.com'; +``` + +## TwitterAuthProvider.credential() + +Creates a credential for Twitter. + +Signature: + +```typescript +static credential(token: string, secret: string): OAuthCredential; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| token | string | Twitter access token. | +| secret | string | Twitter secret. | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) + +## TwitterAuthProvider.credentialFromError() + +Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. + +Signature: + +```typescript +static credentialFromError(error: FirebaseError): OAuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null + +## TwitterAuthProvider.credentialFromResult() + +Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). + +Signature: + +```typescript +static credentialFromResult(userCredential: UserCredential): OAuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null + +### Example 1 + + +```javascript +// Sign in using a redirect. +const provider = new TwitterAuthProvider(); +// Start a sign in process for an unauthenticated user. +await signInWithRedirect(auth, provider); +// This will trigger a full page redirect away from your app + +// After returning from the redirect when your app initializes you can obtain the result +const result = await getRedirectResult(auth); +if (result) { + // This is the signed-in user + const user = result.user; + // This gives you a Twitter Access Token and Secret. + const credential = TwitterAuthProvider.credentialFromResult(result); + const token = credential.accessToken; + const secret = credential.secret; +} + +``` + +### Example 2 + + +```javascript +// Sign in using a popup. +const provider = new TwitterAuthProvider(); +const result = await signInWithPopup(auth, provider); + +// The signed-in user info. +const user = result.user; +// This gives you a Twitter Access Token and Secret. +const credential = TwitterAuthProvider.credentialFromResult(result); +const token = credential.accessToken; +const secret = credential.secret; + +``` + diff --git a/docs-devsite/auth.user.md b/docs-devsite/auth.user.md new file mode 100644 index 00000000000..18a56a45901 --- /dev/null +++ b/docs-devsite/auth.user.md @@ -0,0 +1,204 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# User interface +A user account. + +Signature: + +```typescript +export interface User extends UserInfo +``` +Extends: [UserInfo](./auth.userinfo.md#userinfo_interface) + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [emailVerified](./auth.user.md#useremailverified) | boolean | Whether the email has been verified with [sendEmailVerification()](./auth.md#sendemailverification) and [applyActionCode()](./auth.md#applyactioncode). | +| [isAnonymous](./auth.user.md#userisanonymous) | boolean | Whether the user is authenticated using the [ProviderId](./auth.md#providerid).ANONYMOUS provider. | +| [metadata](./auth.user.md#usermetadata) | [UserMetadata](./auth.usermetadata.md#usermetadata_interface) | Additional metadata around user creation and sign-in times. | +| [providerData](./auth.user.md#userproviderdata) | [UserInfo](./auth.userinfo.md#userinfo_interface)\[\] | Additional per provider such as displayName and profile information. | +| [refreshToken](./auth.user.md#userrefreshtoken) | string | Refresh token used to reauthenticate the user. Avoid using this directly and prefer [User.getIdToken()](./auth.user.md#usergetidtoken) to refresh the ID token instead. | +| [tenantId](./auth.user.md#usertenantid) | string \| null | The user's tenant ID. | + +## Methods + +| Method | Description | +| --- | --- | +| [delete()](./auth.user.md#userdelete) | Deletes and signs out the user. | +| [getIdToken(forceRefresh)](./auth.user.md#usergetidtoken) | Returns a JSON Web Token (JWT) used to identify the user to a Firebase service. | +| [getIdTokenResult(forceRefresh)](./auth.user.md#usergetidtokenresult) | Returns a deserialized JSON Web Token (JWT) used to identitfy the user to a Firebase service. | +| [reload()](./auth.user.md#userreload) | Refreshes the user, if signed in. | +| [toJSON()](./auth.user.md#usertojson) | Returns a JSON-serializable representation of this object. | + +## User.emailVerified + +Whether the email has been verified with [sendEmailVerification()](./auth.md#sendemailverification) and [applyActionCode()](./auth.md#applyactioncode). + +Signature: + +```typescript +readonly emailVerified: boolean; +``` + +## User.isAnonymous + +Whether the user is authenticated using the [ProviderId](./auth.md#providerid).ANONYMOUS provider. + +Signature: + +```typescript +readonly isAnonymous: boolean; +``` + +## User.metadata + +Additional metadata around user creation and sign-in times. + +Signature: + +```typescript +readonly metadata: UserMetadata; +``` + +## User.providerData + +Additional per provider such as displayName and profile information. + +Signature: + +```typescript +readonly providerData: UserInfo[]; +``` + +## User.refreshToken + +Refresh token used to reauthenticate the user. Avoid using this directly and prefer [User.getIdToken()](./auth.user.md#usergetidtoken) to refresh the ID token instead. + +Signature: + +```typescript +readonly refreshToken: string; +``` + +## User.tenantId + +The user's tenant ID. + +This is a read-only property, which indicates the tenant ID used to sign in the user. This is null if the user is signed in from the parent project. + +Signature: + +```typescript +readonly tenantId: string | null; +``` + +### Example + + +```javascript +// Set the tenant ID on Auth instance. +auth.tenantId = 'TENANT_PROJECT_ID'; + +// All future sign-in request now include tenant ID. +const result = await signInWithEmailAndPassword(auth, email, password); +// result.user.tenantId should be 'TENANT_PROJECT_ID'. + +``` + +## User.delete() + +Deletes and signs out the user. + +Important: this is a security-sensitive operation that requires the user to have recently signed in. If this requirement isn't met, ask the user to authenticate again and then call one of the reauthentication methods like [reauthenticateWithCredential()](./auth.md#reauthenticatewithcredential). + +Signature: + +```typescript +delete(): Promise; +``` +Returns: + +Promise<void> + +## User.getIdToken() + +Returns a JSON Web Token (JWT) used to identify the user to a Firebase service. + +Returns the current token if it has not expired or if it will not expire in the next five minutes. Otherwise, this will refresh the token and return a new one. + +Signature: + +```typescript +getIdToken(forceRefresh?: boolean): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| forceRefresh | boolean | Force refresh regardless of token expiration. | + +Returns: + +Promise<string> + +## User.getIdTokenResult() + +Returns a deserialized JSON Web Token (JWT) used to identitfy the user to a Firebase service. + +Returns the current token if it has not expired or if it will not expire in the next five minutes. Otherwise, this will refresh the token and return a new one. + +Signature: + +```typescript +getIdTokenResult(forceRefresh?: boolean): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| forceRefresh | boolean | Force refresh regardless of token expiration. | + +Returns: + +Promise<[IdTokenResult](./auth.idtokenresult.md#idtokenresult_interface)> + +## User.reload() + +Refreshes the user, if signed in. + +Signature: + +```typescript +reload(): Promise; +``` +Returns: + +Promise<void> + +## User.toJSON() + +Returns a JSON-serializable representation of this object. + +Signature: + +```typescript +toJSON(): object; +``` +Returns: + +object + +A JSON-serializable representation of this object. + diff --git a/docs-devsite/auth.usercredential.md b/docs-devsite/auth.usercredential.md new file mode 100644 index 00000000000..665a1ec253e --- /dev/null +++ b/docs-devsite/auth.usercredential.md @@ -0,0 +1,59 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# UserCredential interface +A structure containing a [User](./auth.user.md#user_interface), the [OperationType](./auth.md#operationtype), and the provider ID. + +`operationType` could be [OperationType](./auth.md#operationtype).SIGN\_IN for a sign-in operation, [OperationType](./auth.md#operationtype).LINK for a linking operation and [OperationType](./auth.md#operationtype).REAUTHENTICATE for a reauthentication operation. + +Signature: + +```typescript +export interface UserCredential +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [operationType](./auth.usercredential.md#usercredentialoperationtype) | typeof [OperationTypeMap](./auth.md#operationtype)\[keyof typeof [OperationTypeMap](./auth.md#operationtype)\] | The type of operation which was used to authenticate the user (such as sign-in or link). | +| [providerId](./auth.usercredential.md#usercredentialproviderid) | string \| null | The provider which was used to authenticate the user. | +| [user](./auth.usercredential.md#usercredentialuser) | [User](./auth.user.md#user_interface) | The user authenticated by this credential. | + +## UserCredential.operationType + +The type of operation which was used to authenticate the user (such as sign-in or link). + +Signature: + +```typescript +operationType: typeof OperationTypeMap[keyof typeof OperationTypeMap]; +``` + +## UserCredential.providerId + +The provider which was used to authenticate the user. + +Signature: + +```typescript +providerId: string | null; +``` + +## UserCredential.user + +The user authenticated by this credential. + +Signature: + +```typescript +user: User; +``` diff --git a/docs-devsite/auth.userinfo.md b/docs-devsite/auth.userinfo.md new file mode 100644 index 00000000000..7b49dc65f9c --- /dev/null +++ b/docs-devsite/auth.userinfo.md @@ -0,0 +1,92 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# UserInfo interface +User profile information, visible only to the Firebase project's apps. + +Signature: + +```typescript +export interface UserInfo +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [displayName](./auth.userinfo.md#userinfodisplayname) | string \| null | The display name of the user. | +| [email](./auth.userinfo.md#userinfoemail) | string \| null | The email of the user. | +| [phoneNumber](./auth.userinfo.md#userinfophonenumber) | string \| null | The phone number normalized based on the E.164 standard (e.g. +16505550101) for the user. | +| [photoURL](./auth.userinfo.md#userinfophotourl) | string \| null | The profile photo URL of the user. | +| [providerId](./auth.userinfo.md#userinfoproviderid) | string | The provider used to authenticate the user. | +| [uid](./auth.userinfo.md#userinfouid) | string | The user's unique ID, scoped to the project. | + +## UserInfo.displayName + +The display name of the user. + +Signature: + +```typescript +readonly displayName: string | null; +``` + +## UserInfo.email + +The email of the user. + +Signature: + +```typescript +readonly email: string | null; +``` + +## UserInfo.phoneNumber + +The phone number normalized based on the E.164 standard (e.g. +16505550101) for the user. + +This is null if the user has no phone credential linked to the account. + +Signature: + +```typescript +readonly phoneNumber: string | null; +``` + +## UserInfo.photoURL + +The profile photo URL of the user. + +Signature: + +```typescript +readonly photoURL: string | null; +``` + +## UserInfo.providerId + +The provider used to authenticate the user. + +Signature: + +```typescript +readonly providerId: string; +``` + +## UserInfo.uid + +The user's unique ID, scoped to the project. + +Signature: + +```typescript +readonly uid: string; +``` diff --git a/docs-devsite/auth.usermetadata.md b/docs-devsite/auth.usermetadata.md new file mode 100644 index 00000000000..bb65b30eff5 --- /dev/null +++ b/docs-devsite/auth.usermetadata.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# UserMetadata interface +Interface representing a user's metadata. + +Signature: + +```typescript +export interface UserMetadata +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [creationTime](./auth.usermetadata.md#usermetadatacreationtime) | string | Time the user was created. | +| [lastSignInTime](./auth.usermetadata.md#usermetadatalastsignintime) | string | Time the user last signed in. | + +## UserMetadata.creationTime + +Time the user was created. + +Signature: + +```typescript +readonly creationTime?: string; +``` + +## UserMetadata.lastSignInTime + +Time the user last signed in. + +Signature: + +```typescript +readonly lastSignInTime?: string; +``` diff --git a/docs-devsite/database.database.md b/docs-devsite/database.database.md new file mode 100644 index 00000000000..62ce4f8a420 --- /dev/null +++ b/docs-devsite/database.database.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Database class +Class representing a Firebase Realtime Database. + +Signature: + +```typescript +export declare class Database +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [app](./database.database.md#databaseapp) | | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this Realtime Database instance. | +| [type](./database.database.md#databasetype) | | (not declared) | Represents a Database instance. | + +## Database.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this Realtime Database instance. + +Signature: + +```typescript +readonly app: FirebaseApp; +``` + +## Database.type + +Represents a `Database` instance. + +Signature: + +```typescript +readonly 'type' = "database"; +``` diff --git a/docs-devsite/database.databasereference.md b/docs-devsite/database.databasereference.md new file mode 100644 index 00000000000..13f19a3bf4f --- /dev/null +++ b/docs-devsite/database.databasereference.md @@ -0,0 +1,68 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# DatabaseReference interface +A `DatabaseReference` represents a specific location in your Database and can be used for reading or writing data to that Database location. + +You can reference the root or child location in your Database by calling `ref()` or `ref("child/path")`. + +Writing is done with the `set()` method and reading can be done with the `on*()` method. See [https://firebase.google.com/docs/database/web/read-and-write](https://firebase.google.com/docs/database/web/read-and-write) + +Signature: + +```typescript +export declare interface DatabaseReference extends Query +``` +Extends: [Query](./database.query.md#query_interface) + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [key](./database.databasereference.md#databasereferencekey) | string \| null | The last part of the DatabaseReference's path.For example, "ada" is the key for https://<DATABASE_NAME>.firebaseio.com/users/ada.The key of a root DatabaseReference is null. | +| [parent](./database.databasereference.md#databasereferenceparent) | [DatabaseReference](./database.databasereference.md#databasereference_interface) \| null | The parent location of a DatabaseReference.The parent of a root DatabaseReference is null. | +| [root](./database.databasereference.md#databasereferenceroot) | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The root DatabaseReference of the Database. | + +## DatabaseReference.key + +The last part of the `DatabaseReference`'s path. + +For example, `"ada"` is the key for `https://.firebaseio.com/users/ada`. + +The key of a root `DatabaseReference` is `null`. + +Signature: + +```typescript +readonly key: string | null; +``` + +## DatabaseReference.parent + +The parent location of a `DatabaseReference`. + +The parent of a root `DatabaseReference` is `null`. + +Signature: + +```typescript +readonly parent: DatabaseReference | null; +``` + +## DatabaseReference.root + +The root `DatabaseReference` of the Database. + +Signature: + +```typescript +readonly root: DatabaseReference; +``` diff --git a/docs-devsite/database.datasnapshot.md b/docs-devsite/database.datasnapshot.md new file mode 100644 index 00000000000..35e983def87 --- /dev/null +++ b/docs-devsite/database.datasnapshot.md @@ -0,0 +1,237 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# DataSnapshot class +A `DataSnapshot` contains data from a Database location. + +Any time you read data from the Database, you receive the data as a `DataSnapshot`. A `DataSnapshot` is passed to the event callbacks you attach with `on()` or `once()`. You can extract the contents of the snapshot as a JavaScript object by calling the `val()` method. Alternatively, you can traverse into the snapshot by calling `child()` to return child snapshots (which you could then call `val()` on). + +A `DataSnapshot` is an efficiently generated, immutable copy of the data at a Database location. It cannot be modified and will never change (to modify data, you always call the `set()` method on a `Reference` directly). + +Signature: + +```typescript +export declare class DataSnapshot +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [key](./database.datasnapshot.md#datasnapshotkey) | | string \| null | The key (last part of the path) of the location of this DataSnapshot.The last token in a Database location is considered its key. For example, "ada" is the key for the /users/ada/ node. Accessing the key on any DataSnapshot will return the key for the location that generated it. However, accessing the key on the root URL of a Database will return null. | +| [priority](./database.datasnapshot.md#datasnapshotpriority) | | string \| number \| null | Gets the priority value of the data in this DataSnapshot.Applications need not use priority but can order collections by ordinary properties (see [Sorting and filtering data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) ). | +| [ref](./database.datasnapshot.md#datasnapshotref) | | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location of this DataSnapshot. | +| [size](./database.datasnapshot.md#datasnapshotsize) | | number | Returns the number of child properties of this DataSnapshot. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [child(path)](./database.datasnapshot.md#datasnapshotchild) | | Gets another DataSnapshot for the location at the specified relative path.Passing a relative path to the child() method of a DataSnapshot returns another DataSnapshot for the location at the specified relative path. The relative path can either be a simple child name (for example, "ada") or a deeper, slash-separated path (for example, "ada/name/first"). If the child location has no data, an empty DataSnapshot (that is, a DataSnapshot whose value is null) is returned. | +| [exists()](./database.datasnapshot.md#datasnapshotexists) | | Returns true if this DataSnapshot contains any data. It is slightly more efficient than using snapshot.val() !== null. | +| [exportVal()](./database.datasnapshot.md#datasnapshotexportval) | | Exports the entire contents of the DataSnapshot as a JavaScript object.The exportVal() method is similar to val(), except priority information is included (if available), making it suitable for backing up your data. | +| [forEach(action)](./database.datasnapshot.md#datasnapshotforeach) | | Enumerates the top-level children in the DataSnapshot.Because of the way JavaScript objects work, the ordering of data in the JavaScript object returned by val() is not guaranteed to match the ordering on the server nor the ordering of onChildAdded() events. That is where forEach() comes in handy. It guarantees the children of a DataSnapshot will be iterated in their query order.If no explicit orderBy*() method is used, results are returned ordered by key (unless priorities are used, in which case, results are returned by priority). | +| [hasChild(path)](./database.datasnapshot.md#datasnapshothaschild) | | Returns true if the specified child path has (non-null) data. | +| [hasChildren()](./database.datasnapshot.md#datasnapshothaschildren) | | Returns whether or not the DataSnapshot has any non-null child properties.You can use hasChildren() to determine if a DataSnapshot has any children. If it does, you can enumerate them using forEach(). If it doesn't, then either this snapshot contains a primitive value (which can be retrieved with val()) or it is empty (in which case, val() will return null). | +| [toJSON()](./database.datasnapshot.md#datasnapshottojson) | | Returns a JSON-serializable representation of this object. | +| [val()](./database.datasnapshot.md#datasnapshotval) | | Extracts a JavaScript value from a DataSnapshot.Depending on the data in a DataSnapshot, the val() method may return a scalar type (string, number, or boolean), an array, or an object. It may also return null, indicating that the DataSnapshot is empty (contains no data). | + +## DataSnapshot.key + +The key (last part of the path) of the location of this `DataSnapshot`. + +The last token in a Database location is considered its key. For example, "ada" is the key for the /users/ada/ node. Accessing the key on any `DataSnapshot` will return the key for the location that generated it. However, accessing the key on the root URL of a Database will return `null`. + +Signature: + +```typescript +get key(): string | null; +``` + +## DataSnapshot.priority + +Gets the priority value of the data in this `DataSnapshot`. + +Applications need not use priority but can order collections by ordinary properties (see [Sorting and filtering data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) ). + +Signature: + +```typescript +get priority(): string | number | null; +``` + +## DataSnapshot.ref + +The location of this DataSnapshot. + +Signature: + +```typescript +readonly ref: DatabaseReference; +``` + +## DataSnapshot.size + +Returns the number of child properties of this `DataSnapshot`. + +Signature: + +```typescript +get size(): number; +``` + +## DataSnapshot.child() + +Gets another `DataSnapshot` for the location at the specified relative path. + +Passing a relative path to the `child()` method of a DataSnapshot returns another `DataSnapshot` for the location at the specified relative path. The relative path can either be a simple child name (for example, "ada") or a deeper, slash-separated path (for example, "ada/name/first"). If the child location has no data, an empty `DataSnapshot` (that is, a `DataSnapshot` whose value is `null`) is returned. + +Signature: + +```typescript +child(path: string): DataSnapshot; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| path | string | A relative path to the location of child data. | + +Returns: + +[DataSnapshot](./database.datasnapshot.md#datasnapshot_class) + +## DataSnapshot.exists() + +Returns true if this `DataSnapshot` contains any data. It is slightly more efficient than using `snapshot.val() !== null`. + +Signature: + +```typescript +exists(): boolean; +``` +Returns: + +boolean + +## DataSnapshot.exportVal() + +Exports the entire contents of the DataSnapshot as a JavaScript object. + +The `exportVal()` method is similar to `val()`, except priority information is included (if available), making it suitable for backing up your data. + +Signature: + +```typescript +exportVal(): any; +``` +Returns: + +any + +The DataSnapshot's contents as a JavaScript value (Object, Array, string, number, boolean, or `null`). + +## DataSnapshot.forEach() + +Enumerates the top-level children in the `DataSnapshot`. + +Because of the way JavaScript objects work, the ordering of data in the JavaScript object returned by `val()` is not guaranteed to match the ordering on the server nor the ordering of `onChildAdded()` events. That is where `forEach()` comes in handy. It guarantees the children of a `DataSnapshot` will be iterated in their query order. + +If no explicit `orderBy*()` method is used, results are returned ordered by key (unless priorities are used, in which case, results are returned by priority). + +Signature: + +```typescript +forEach(action: (child: DataSnapshot) => boolean | void): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| action | (child: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => boolean \| void | A function that will be called for each child DataSnapshot. The callback can return true to cancel further enumeration. | + +Returns: + +boolean + +true if enumeration was canceled due to your callback returning true. + +## DataSnapshot.hasChild() + +Returns true if the specified child path has (non-null) data. + +Signature: + +```typescript +hasChild(path: string): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| path | string | A relative path to the location of a potential child. | + +Returns: + +boolean + +`true` if data exists at the specified child path; else `false`. + +## DataSnapshot.hasChildren() + +Returns whether or not the `DataSnapshot` has any non-`null` child properties. + +You can use `hasChildren()` to determine if a `DataSnapshot` has any children. If it does, you can enumerate them using `forEach()`. If it doesn't, then either this snapshot contains a primitive value (which can be retrieved with `val()`) or it is empty (in which case, `val()` will return `null`). + +Signature: + +```typescript +hasChildren(): boolean; +``` +Returns: + +boolean + +true if this snapshot has any children; else false. + +## DataSnapshot.toJSON() + +Returns a JSON-serializable representation of this object. + +Signature: + +```typescript +toJSON(): object | null; +``` +Returns: + +object \| null + +## DataSnapshot.val() + +Extracts a JavaScript value from a `DataSnapshot`. + +Depending on the data in a `DataSnapshot`, the `val()` method may return a scalar type (string, number, or boolean), an array, or an object. It may also return null, indicating that the `DataSnapshot` is empty (contains no data). + +Signature: + +```typescript +val(): any; +``` +Returns: + +any + +The DataSnapshot's contents as a JavaScript value (Object, Array, string, number, boolean, or `null`). + diff --git a/docs-devsite/database.listenoptions.md b/docs-devsite/database.listenoptions.md new file mode 100644 index 00000000000..171067dd020 --- /dev/null +++ b/docs-devsite/database.listenoptions.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ListenOptions interface +An options objects that can be used to customize a listener. + +Signature: + +```typescript +export declare interface ListenOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [onlyOnce](./database.listenoptions.md#listenoptionsonlyonce) | boolean | Whether to remove the listener after its first invocation. | + +## ListenOptions.onlyOnce + +Whether to remove the listener after its first invocation. + +Signature: + +```typescript +readonly onlyOnce?: boolean; +``` diff --git a/docs-devsite/database.md b/docs-devsite/database.md new file mode 100644 index 00000000000..686ca7f8580 --- /dev/null +++ b/docs-devsite/database.md @@ -0,0 +1,1405 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# database package +Firebase Realtime Database + +## Functions + +| Function | Description | +| --- | --- | +| function(app...) | +| [getDatabase(app, url)](./database.md#getdatabase) | Returns the instance of the Realtime Database SDK that is associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). Initializes a new instance with with default settings if no instance exists or if the existing instance uses a custom database URL. | +| function(db...) | +| [connectDatabaseEmulator(db, host, port, options)](./database.md#connectdatabaseemulator) | Modify the provided instance to communicate with the Realtime Database emulator.

Note: This method must be called before performing any other operation. | +| [goOffline(db)](./database.md#gooffline) | Disconnects from the server (all Database operations will be completed offline).The client automatically maintains a persistent connection to the Database server, which will remain active indefinitely and reconnect when disconnected. However, the goOffline() and goOnline() methods may be used to control the client connection in cases where a persistent connection is undesirable.While offline, the client will no longer receive data updates from the Database. However, all Database operations performed locally will continue to immediately fire events, allowing your application to continue behaving normally. Additionally, each operation performed locally will automatically be queued and retried upon reconnection to the Database server.To reconnect to the Database and begin receiving remote events, see goOnline(). | +| [goOnline(db)](./database.md#goonline) | Reconnects to the server and synchronizes the offline Database state with the server state.This method should be used after disabling the active connection with goOffline(). Once reconnected, the client will transmit the proper data and fire the appropriate events so that your client "catches up" automatically. | +| [ref(db, path)](./database.md#ref) | Returns a Reference representing the location in the Database corresponding to the provided path. If no path is provided, the Reference will point to the root of the Database. | +| [refFromURL(db, url)](./database.md#reffromurl) | Returns a Reference representing the location in the Database corresponding to the provided Firebase URL.An exception is thrown if the URL is not a valid Firebase Database URL or it has a different domain than the current Database instance.Note that all query parameters (orderBy, limitToLast, etc.) are ignored and are not applied to the returned Reference. | +| function() | +| [forceLongPolling()](./database.md#forcelongpolling) | Force the use of longPolling instead of websockets. This will be ignored if websocket protocol is used in databaseURL. | +| [forceWebSockets()](./database.md#forcewebsockets) | Force the use of websockets instead of longPolling. | +| [orderByKey()](./database.md#orderbykey) | Creates a new QueryConstraint that orders by the key.Sorts the results of a query by their (ascending) key values.You can read more about orderByKey() in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). | +| [orderByPriority()](./database.md#orderbypriority) | Creates a new QueryConstraint that orders by priority.Applications need not use priority but can order collections by ordinary properties (see [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data) for alternatives to priority. | +| [orderByValue()](./database.md#orderbyvalue) | Creates a new QueryConstraint that orders by value.If the children of a query are all scalar values (string, number, or boolean), you can order the results by their (ascending) values.You can read more about orderByValue() in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). | +| [serverTimestamp()](./database.md#servertimestamp) | Returns a placeholder value for auto-populating the current timestamp (time since the Unix epoch, in milliseconds) as determined by the Firebase servers. | +| function(delta...) | +| [increment(delta)](./database.md#increment) | Returns a placeholder value that can be used to atomically increment the current database value by the provided delta. | +| function(enabled...) | +| [enableLogging(enabled, persistent)](./database.md#enablelogging) | Logs debugging information to the console. | +| function(limit...) | +| [limitToFirst(limit)](./database.md#limittofirst) | Creates a new QueryConstraint that if limited to the first specific number of children.The limitToFirst() method is used to set a maximum number of children to be synced for a given callback. If we set a limit of 100, we will initially only receive up to 100 child_added events. If we have fewer than 100 messages stored in our Database, a child_added event will fire for each message. However, if we have over 100 messages, we will only receive a child_added event for the first 100 ordered messages. As items change, we will receive child_removed events for each item that drops out of the active list so that the total number stays at 100.You can read more about limitToFirst() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | +| [limitToLast(limit)](./database.md#limittolast) | Creates a new QueryConstraint that is limited to return only the last specified number of children.The limitToLast() method is used to set a maximum number of children to be synced for a given callback. If we set a limit of 100, we will initially only receive up to 100 child_added events. If we have fewer than 100 messages stored in our Database, a child_added event will fire for each message. However, if we have over 100 messages, we will only receive a child_added event for the last 100 ordered messages. As items change, we will receive child_removed events for each item that drops out of the active list so that the total number stays at 100.You can read more about limitToLast() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | +| function(logger...) | +| [enableLogging(logger)](./database.md#enablelogging) | Logs debugging information to the console. | +| function(parent...) | +| [child(parent, path)](./database.md#child) | Gets a Reference for the location at the specified relative path.The relative path can either be a simple child name (for example, "ada") or a deeper slash-separated path (for example, "ada/name/first"). | +| [push(parent, value)](./database.md#push) | Generates a new child location using a unique key and returns its Reference.This is the most common pattern for adding data to a collection of items.If you provide a value to push(), the value is written to the generated location. If you don't pass a value, nothing is written to the database and the child remains empty (but you can use the Reference elsewhere).The unique keys generated by push() are ordered by the current time, so the resulting list of items is chronologically sorted. The keys are also designed to be unguessable (they contain 72 random bits of entropy).See [Append to a list of data](https://firebase.google.com/docs/database/web/lists-of-data#append_to_a_list_of_data). See [The 2^120 Ways to Ensure Unique Identifiers](https://firebase.googleblog.com/2015/02/the-2120-ways-to-ensure-unique_68.html). | +| function(path...) | +| [orderByChild(path)](./database.md#orderbychild) | Creates a new QueryConstraint that orders by the specified child key.Queries can only order by one key at a time. Calling orderByChild() multiple times on the same query is an error.Firebase queries allow you to order your data by any child key on the fly. However, if you know in advance what your indexes will be, you can define them via the .indexOn rule in your Security Rules for better performance. See the[https://firebase.google.com/docs/database/security/indexing-data](https://firebase.google.com/docs/database/security/indexing-data) rule for more information.You can read more about orderByChild() in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). | +| function(query...) | +| [get(query)](./database.md#get) | Gets the most up-to-date result for this query. | +| [off(query, eventType, callback)](./database.md#off) | Detaches a callback previously attached with the corresponding on*() (onValue, onChildAdded) listener. Note: This is not the recommended way to remove a listener. Instead, please use the returned callback function from the respective on* callbacks.Detach a callback previously attached with on*(). Calling off() on a parent listener will not automatically remove listeners registered on child nodes, off() must also be called on any child listeners to remove the callback.If a callback is not specified, all callbacks for the specified eventType will be removed. Similarly, if no eventType is specified, all callbacks for the Reference will be removed.Individual listeners can also be removed by invoking their unsubscribe callbacks. | +| [onChildAdded(query, callback, cancelCallback)](./database.md#onchildadded) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildAdded event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The DataSnapshot passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | +| [onChildAdded(query, callback, options)](./database.md#onchildadded) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildAdded event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The DataSnapshot passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | +| [onChildAdded(query, callback, cancelCallback, options)](./database.md#onchildadded) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildAdded event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The DataSnapshot passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | +| [onChildChanged(query, callback, cancelCallback)](./database.md#onchildchanged) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildChanged event will be triggered when the data stored in a child (or any of its descendants) changes. Note that a single child_changed event may represent multiple changes to the child. The DataSnapshot passed to the callback will contain the new child contents. For ordering purposes, the callback is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | +| [onChildChanged(query, callback, options)](./database.md#onchildchanged) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildChanged event will be triggered when the data stored in a child (or any of its descendants) changes. Note that a single child_changed event may represent multiple changes to the child. The DataSnapshot passed to the callback will contain the new child contents. For ordering purposes, the callback is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | +| [onChildChanged(query, callback, cancelCallback, options)](./database.md#onchildchanged) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildChanged event will be triggered when the data stored in a child (or any of its descendants) changes. Note that a single child_changed event may represent multiple changes to the child. The DataSnapshot passed to the callback will contain the new child contents. For ordering purposes, the callback is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | +| [onChildMoved(query, callback, cancelCallback)](./database.md#onchildmoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildMoved event will be triggered when a child's sort order changes such that its position relative to its siblings changes. The DataSnapshot passed to the callback will be for the data of the child that has moved. It is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | +| [onChildMoved(query, callback, options)](./database.md#onchildmoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildMoved event will be triggered when a child's sort order changes such that its position relative to its siblings changes. The DataSnapshot passed to the callback will be for the data of the child that has moved. It is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | +| [onChildMoved(query, callback, cancelCallback, options)](./database.md#onchildmoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildMoved event will be triggered when a child's sort order changes such that its position relative to its siblings changes. The DataSnapshot passed to the callback will be for the data of the child that has moved. It is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | +| [onChildRemoved(query, callback, cancelCallback)](./database.md#onchildremoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildRemoved event will be triggered once every time a child is removed. The DataSnapshot passed into the callback will be the old data for the child that was removed. A child will get removed when either:- a client explicitly calls remove() on that child or one of its ancestors - a client calls set(null) on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) | +| [onChildRemoved(query, callback, options)](./database.md#onchildremoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildRemoved event will be triggered once every time a child is removed. The DataSnapshot passed into the callback will be the old data for the child that was removed. A child will get removed when either:- a client explicitly calls remove() on that child or one of its ancestors - a client calls set(null) on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) | +| [onChildRemoved(query, callback, cancelCallback, options)](./database.md#onchildremoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildRemoved event will be triggered once every time a child is removed. The DataSnapshot passed into the callback will be the old data for the child that was removed. A child will get removed when either:- a client explicitly calls remove() on that child or one of its ancestors - a client calls set(null) on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) | +| [onValue(query, callback, cancelCallback)](./database.md#onvalue) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onValue event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The DataSnapshot passed to the callback will be for the location at which on() was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty DataSnapshot (val() will return null). | +| [onValue(query, callback, options)](./database.md#onvalue) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onValue event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The DataSnapshot passed to the callback will be for the location at which on() was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty DataSnapshot (val() will return null). | +| [onValue(query, callback, cancelCallback, options)](./database.md#onvalue) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onValue event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The DataSnapshot passed to the callback will be for the location at which on() was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty DataSnapshot (val() will return null). | +| [query(query, queryConstraints)](./database.md#query) | Creates a new immutable instance of Query that is extended to also include additional query constraints. | +| function(ref...) | +| [onDisconnect(ref)](./database.md#ondisconnect) | Returns an OnDisconnect object - see [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information on how to use it. | +| [remove(ref)](./database.md#remove) | Removes the data at this Database location.Any data at child locations will also be deleted.The effect of the remove will be visible immediately and the corresponding event 'value' will be triggered. Synchronization of the remove to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the onComplete callback will be called asynchronously after synchronization has finished. | +| [runTransaction(ref, transactionUpdate, options)](./database.md#runtransaction) | Atomically modifies the data at this location.Atomically modify the data at this location. Unlike a normal set(), which just overwrites the data regardless of its previous value, runTransaction() is used to modify the existing value to a new value, ensuring there are no conflicts with other clients writing to the same location at the same time.To accomplish this, you pass runTransaction() an update function which is used to transform the current value into a new value. If another client writes to the location before your new value is successfully written, your update function will be called again with the new current value, and the write will be retried. This will happen repeatedly until your write succeeds without conflict or you abort the transaction by not returning a value from your update function.Note: Modifying data with set() will cancel any pending transactions at that location, so extreme care should be taken if mixing set() and runTransaction() to update the same data.Note: When using transactions with Security and Firebase Rules in place, be aware that a client needs .read access in addition to .write access in order to perform a transaction. This is because the client-side nature of transactions requires the client to read the data in order to transactionally update it. | +| [set(ref, value)](./database.md#set) | Writes data to this Database location.This will overwrite any data at this location and all child locations.The effect of the write will be visible immediately, and the corresponding events ("value", "child\_added", etc.) will be triggered. Synchronization of the data to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the onComplete callback will be called asynchronously after synchronization has finished.Passing null for the new value is equivalent to calling remove(); namely, all data at this location and all child locations will be deleted.set() will remove any priority stored at this location, so if priority is meant to be preserved, you need to use setWithPriority() instead.Note that modifying data with set() will cancel any pending transactions at that location, so extreme care should be taken if mixing set() and transaction() to modify the same data.A single set() will generate a single "value" event at the location where the set() was performed. | +| [setPriority(ref, priority)](./database.md#setpriority) | Sets a priority for the data at this Database location.Applications need not use priority but can order collections by ordinary properties (see [Sorting and filtering data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) ). | +| [setWithPriority(ref, value, priority)](./database.md#setwithpriority) | Writes data the Database location. Like set() but also specifies the priority for that data.Applications need not use priority but can order collections by ordinary properties (see [Sorting and filtering data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) ). | +| [update(ref, values)](./database.md#update) | Writes multiple values to the Database at once.The values argument contains multiple property-value pairs that will be written to the Database together. Each child property can either be a simple property (for example, "name") or a relative path (for example, "name/first") from the current location to the data to update.As opposed to the set() method, update() can be use to selectively update only the referenced properties at the current location (instead of replacing all the child properties at the current location).The effect of the write will be visible immediately, and the corresponding events ('value', 'child\_added', etc.) will be triggered. Synchronization of the data to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the onComplete callback will be called asynchronously after synchronization has finished.A single update() will generate a single "value" event at the location where the update() was performed, regardless of how many children were modified.Note that modifying data with update() will cancel any pending transactions at that location, so extreme care should be taken if mixing update() and transaction() to modify the same data.Passing null to update() will remove the data at this location.See [Introducing multi-location updates and more](https://firebase.googleblog.com/2015/09/introducing-multi-location-updates-and_86.html). | +| function(value...) | +| [endAt(value, key)](./database.md#endat) | Creates a QueryConstraint with the specified ending point.Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The ending point is inclusive, so children with exactly the specified value will be included in the query. The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have a key name less than or equal to the specified key.You can read more about endAt() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | +| [endBefore(value, key)](./database.md#endbefore) | Creates a QueryConstraint with the specified ending point (exclusive).Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The ending point is exclusive. If only a value is provided, children with a value less than the specified value will be included in the query. If a key is specified, then children must have a value less than or equal to the specified value and a key name less than the specified key. | +| [equalTo(value, key)](./database.md#equalto) | Creates a QueryConstraint that includes children that match the specified value.Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have exactly the specified key as their key name. This can be used to filter result sets with many matches for the same value.You can read more about equalTo() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | +| [startAfter(value, key)](./database.md#startafter) | Creates a QueryConstraint with the specified starting point (exclusive).Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The starting point is exclusive. If only a value is provided, children with a value greater than the specified value will be included in the query. If a key is specified, then children must have a value greater than or equal to the specified value and a a key name greater than the specified key. | +| [startAt(value, key)](./database.md#startat) | Creates a QueryConstraint with the specified starting point.Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The starting point is inclusive, so children with exactly the specified value will be included in the query. The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have a key name greater than or equal to the specified key.You can read more about startAt() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | + +## Classes + +| Class | Description | +| --- | --- | +| [Database](./database.database.md#database_class) | Class representing a Firebase Realtime Database. | +| [DataSnapshot](./database.datasnapshot.md#datasnapshot_class) | A DataSnapshot contains data from a Database location.Any time you read data from the Database, you receive the data as a DataSnapshot. A DataSnapshot is passed to the event callbacks you attach with on() or once(). You can extract the contents of the snapshot as a JavaScript object by calling the val() method. Alternatively, you can traverse into the snapshot by calling child() to return child snapshots (which you could then call val() on).A DataSnapshot is an efficiently generated, immutable copy of the data at a Database location. It cannot be modified and will never change (to modify data, you always call the set() method on a Reference directly). | +| [OnDisconnect](./database.ondisconnect.md#ondisconnect_class) | The onDisconnect class allows you to write or clear data when your client disconnects from the Database server. These updates occur whether your client disconnects cleanly or not, so you can rely on them to clean up data even if a connection is dropped or a client crashes.The onDisconnect class is most commonly used to manage presence in applications where it is useful to detect how many clients are connected and when other clients disconnect. See [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information.To avoid problems when a connection is dropped before the requests can be transferred to the Database server, these functions should be called before writing any data.Note that onDisconnect operations are only triggered once. If you want an operation to occur each time a disconnect occurs, you'll need to re-establish the onDisconnect operations each time you reconnect. | +| [QueryConstraint](./database.queryconstraint.md#queryconstraint_class) | A QueryConstraint is used to narrow the set of documents returned by a Database query. QueryConstraints are created by invoking [endAt()](./database.md#endat), [endBefore()](./database.md#endbefore), [startAt()](./database.md#startat), [startAfter()](./database.md#startafter), [limitToFirst()](./database.md#limittofirst), [limitToLast()](./database.md#limittolast), [orderByChild()](./database.md#orderbychild), [orderByChild()](./database.md#orderbychild), [orderByKey()](./database.md#orderbykey) , [orderByPriority()](./database.md#orderbypriority) , [orderByValue()](./database.md#orderbyvalue) or [equalTo()](./database.md#equalto) and can then be passed to [query()](./database.md#query) to create a new query instance that also contains this QueryConstraint. | +| [TransactionResult](./database.transactionresult.md#transactionresult_class) | A type for the resolve value of [runTransaction()](./database.md#runtransaction). | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [DatabaseReference](./database.databasereference.md#databasereference_interface) | A DatabaseReference represents a specific location in your Database and can be used for reading or writing data to that Database location.You can reference the root or child location in your Database by calling ref() or ref("child/path").Writing is done with the set() method and reading can be done with the on*() method. See [https://firebase.google.com/docs/database/web/read-and-write](https://firebase.google.com/docs/database/web/read-and-write) | +| [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An options objects that can be used to customize a listener. | +| [Query](./database.query.md#query_interface) | A Query sorts and filters the data at a Database location so only a subset of the child data is included. This can be used to order a collection of data by some attribute (for example, height of dinosaurs) as well as to restrict a large list of items (for example, chat messages) down to a number suitable for synchronizing to the client. Queries are created by chaining together one or more of the filter methods defined here.Just as with a DatabaseReference, you can receive data from a Query by using the on*() methods. You will only receive events and DataSnapshots for the subset of the data that matches your query.See [https://firebase.google.com/docs/database/web/lists-of-data\#sorting\_and\_filtering\_data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) for more information. | +| [ThenableReference](./database.thenablereference.md#thenablereference_interface) | A Promise that can also act as a DatabaseReference when returned by [push()](./database.md#push). The reference is available immediately and the Promise resolves as the write to the backend completes. | +| [TransactionOptions](./database.transactionoptions.md#transactionoptions_interface) | An options object to configure transactions. | + +## Type Aliases + +| Type Alias | Description | +| --- | --- | +| [EventType](./database.md#eventtype) | One of the following strings: "value", "child\_added", "child\_changed", "child\_removed", or "child\_moved." | +| [QueryConstraintType](./database.md#queryconstrainttype) | Describes the different query constraints available in this SDK. | +| [Unsubscribe](./database.md#unsubscribe) | A callback that can invoked to remove a listener. | + +## getDatabase() + +Returns the instance of the Realtime Database SDK that is associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). Initializes a new instance with with default settings if no instance exists or if the existing instance uses a custom database URL. + +Signature: + +```typescript +export declare function getDatabase(app?: FirebaseApp, url?: string): Database; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance that the returned Realtime Database instance is associated with. | +| url | string | The URL of the Realtime Database instance to connect to. If not provided, the SDK connects to the default instance of the Firebase App. | + +Returns: + +[Database](./database.database.md#database_class) + +The `Database` instance of the provided app. + +## connectDatabaseEmulator() + +Modify the provided instance to communicate with the Realtime Database emulator. + +

Note: This method must be called before performing any other operation. + +Signature: + +```typescript +export declare function connectDatabaseEmulator(db: Database, host: string, port: number, options?: { + mockUserToken?: EmulatorMockTokenOptions | string; +}): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| db | [Database](./database.database.md#database_class) | The instance to modify. | +| host | string | The emulator host (ex: localhost) | +| port | number | The emulator port (ex: 8080) | +| options | { mockUserToken?: [EmulatorMockTokenOptions](./util.md#emulatormocktokenoptions) \| string; } | | + +Returns: + +void + +## goOffline() + +Disconnects from the server (all Database operations will be completed offline). + +The client automatically maintains a persistent connection to the Database server, which will remain active indefinitely and reconnect when disconnected. However, the `goOffline()` and `goOnline()` methods may be used to control the client connection in cases where a persistent connection is undesirable. + +While offline, the client will no longer receive data updates from the Database. However, all Database operations performed locally will continue to immediately fire events, allowing your application to continue behaving normally. Additionally, each operation performed locally will automatically be queued and retried upon reconnection to the Database server. + +To reconnect to the Database and begin receiving remote events, see `goOnline()`. + +Signature: + +```typescript +export declare function goOffline(db: Database): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| db | [Database](./database.database.md#database_class) | The instance to disconnect. | + +Returns: + +void + +## goOnline() + +Reconnects to the server and synchronizes the offline Database state with the server state. + +This method should be used after disabling the active connection with `goOffline()`. Once reconnected, the client will transmit the proper data and fire the appropriate events so that your client "catches up" automatically. + +Signature: + +```typescript +export declare function goOnline(db: Database): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| db | [Database](./database.database.md#database_class) | The instance to reconnect. | + +Returns: + +void + +## ref() + +Returns a `Reference` representing the location in the Database corresponding to the provided path. If no path is provided, the `Reference` will point to the root of the Database. + +Signature: + +```typescript +export declare function ref(db: Database, path?: string): DatabaseReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| db | [Database](./database.database.md#database_class) | The database instance to obtain a reference for. | +| path | string | Optional path representing the location the returned Reference will point. If not provided, the returned Reference will point to the root of the Database. | + +Returns: + +[DatabaseReference](./database.databasereference.md#databasereference_interface) + +If a path is provided, a `Reference` pointing to the provided path. Otherwise, a `Reference` pointing to the root of the Database. + +## refFromURL() + +Returns a `Reference` representing the location in the Database corresponding to the provided Firebase URL. + +An exception is thrown if the URL is not a valid Firebase Database URL or it has a different domain than the current `Database` instance. + +Note that all query parameters (`orderBy`, `limitToLast`, etc.) are ignored and are not applied to the returned `Reference`. + +Signature: + +```typescript +export declare function refFromURL(db: Database, url: string): DatabaseReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| db | [Database](./database.database.md#database_class) | The database instance to obtain a reference for. | +| url | string | The Firebase URL at which the returned Reference will point. | + +Returns: + +[DatabaseReference](./database.databasereference.md#databasereference_interface) + +A `Reference` pointing to the provided Firebase URL. + +## forceLongPolling() + +Force the use of longPolling instead of websockets. This will be ignored if websocket protocol is used in databaseURL. + +Signature: + +```typescript +export declare function forceLongPolling(): void; +``` +Returns: + +void + +## forceWebSockets() + +Force the use of websockets instead of longPolling. + +Signature: + +```typescript +export declare function forceWebSockets(): void; +``` +Returns: + +void + +## orderByKey() + +Creates a new `QueryConstraint` that orders by the key. + +Sorts the results of a query by their (ascending) key values. + +You can read more about `orderByKey()` in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). + +Signature: + +```typescript +export declare function orderByKey(): QueryConstraint; +``` +Returns: + +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) + +## orderByPriority() + +Creates a new `QueryConstraint` that orders by priority. + +Applications need not use priority but can order collections by ordinary properties (see [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data) for alternatives to priority. + +Signature: + +```typescript +export declare function orderByPriority(): QueryConstraint; +``` +Returns: + +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) + +## orderByValue() + +Creates a new `QueryConstraint` that orders by value. + +If the children of a query are all scalar values (string, number, or boolean), you can order the results by their (ascending) values. + +You can read more about `orderByValue()` in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). + +Signature: + +```typescript +export declare function orderByValue(): QueryConstraint; +``` +Returns: + +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) + +## serverTimestamp() + +Returns a placeholder value for auto-populating the current timestamp (time since the Unix epoch, in milliseconds) as determined by the Firebase servers. + +Signature: + +```typescript +export declare function serverTimestamp(): object; +``` +Returns: + +object + +## increment() + +Returns a placeholder value that can be used to atomically increment the current database value by the provided delta. + +Signature: + +```typescript +export declare function increment(delta: number): object; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| delta | number | the amount to modify the current value atomically. | + +Returns: + +object + +A placeholder value for modifying data atomically server-side. + +## enableLogging() + +Logs debugging information to the console. + +Signature: + +```typescript +export declare function enableLogging(enabled: boolean, persistent?: boolean): any; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| enabled | boolean | Enables logging if true, disables logging if false. | +| persistent | boolean | Remembers the logging state between page refreshes if true. | + +Returns: + +any + +## limitToFirst() + +Creates a new `QueryConstraint` that if limited to the first specific number of children. + +The `limitToFirst()` method is used to set a maximum number of children to be synced for a given callback. If we set a limit of 100, we will initially only receive up to 100 `child_added` events. If we have fewer than 100 messages stored in our Database, a `child_added` event will fire for each message. However, if we have over 100 messages, we will only receive a `child_added` event for the first 100 ordered messages. As items change, we will receive `child_removed` events for each item that drops out of the active list so that the total number stays at 100. + +You can read more about `limitToFirst()` in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). + +Signature: + +```typescript +export declare function limitToFirst(limit: number): QueryConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| limit | number | The maximum number of nodes to include in this query. | + +Returns: + +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) + +## limitToLast() + +Creates a new `QueryConstraint` that is limited to return only the last specified number of children. + +The `limitToLast()` method is used to set a maximum number of children to be synced for a given callback. If we set a limit of 100, we will initially only receive up to 100 `child_added` events. If we have fewer than 100 messages stored in our Database, a `child_added` event will fire for each message. However, if we have over 100 messages, we will only receive a `child_added` event for the last 100 ordered messages. As items change, we will receive `child_removed` events for each item that drops out of the active list so that the total number stays at 100. + +You can read more about `limitToLast()` in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). + +Signature: + +```typescript +export declare function limitToLast(limit: number): QueryConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| limit | number | The maximum number of nodes to include in this query. | + +Returns: + +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) + +## enableLogging() + +Logs debugging information to the console. + +Signature: + +```typescript +export declare function enableLogging(logger: (message: string) => unknown): any; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| logger | (message: string) => unknown | A custom logger function to control how things get logged. | + +Returns: + +any + +## child() + +Gets a `Reference` for the location at the specified relative path. + +The relative path can either be a simple child name (for example, "ada") or a deeper slash-separated path (for example, "ada/name/first"). + +Signature: + +```typescript +export declare function child(parent: DatabaseReference, path: string): DatabaseReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| parent | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The parent location. | +| path | string | A relative path from this location to the desired child location. | + +Returns: + +[DatabaseReference](./database.databasereference.md#databasereference_interface) + +The specified child location. + +## push() + +Generates a new child location using a unique key and returns its `Reference`. + +This is the most common pattern for adding data to a collection of items. + +If you provide a value to `push()`, the value is written to the generated location. If you don't pass a value, nothing is written to the database and the child remains empty (but you can use the `Reference` elsewhere). + +The unique keys generated by `push()` are ordered by the current time, so the resulting list of items is chronologically sorted. The keys are also designed to be unguessable (they contain 72 random bits of entropy). + +See [Append to a list of data](https://firebase.google.com/docs/database/web/lists-of-data#append_to_a_list_of_data). See [The 2^120 Ways to Ensure Unique Identifiers](https://firebase.googleblog.com/2015/02/the-2120-ways-to-ensure-unique_68.html). + +Signature: + +```typescript +export declare function push(parent: DatabaseReference, value?: unknown): ThenableReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| parent | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The parent location. | +| value | unknown | Optional value to be written at the generated location. | + +Returns: + +[ThenableReference](./database.thenablereference.md#thenablereference_interface) + +Combined `Promise` and `Reference`; resolves when write is complete, but can be used immediately as the `Reference` to the child location. + +## orderByChild() + +Creates a new `QueryConstraint` that orders by the specified child key. + +Queries can only order by one key at a time. Calling `orderByChild()` multiple times on the same query is an error. + +Firebase queries allow you to order your data by any child key on the fly. However, if you know in advance what your indexes will be, you can define them via the .indexOn rule in your Security Rules for better performance. See the[https://firebase.google.com/docs/database/security/indexing-data](https://firebase.google.com/docs/database/security/indexing-data) rule for more information. + +You can read more about `orderByChild()` in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). + +Signature: + +```typescript +export declare function orderByChild(path: string): QueryConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| path | string | The path to order by. | + +Returns: + +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) + +## get() + +Gets the most up-to-date result for this query. + +Signature: + +```typescript +export declare function get(query: Query): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | + +Returns: + +Promise<[DataSnapshot](./database.datasnapshot.md#datasnapshot_class)> + +A `Promise` which resolves to the resulting DataSnapshot if a value is available, or rejects if the client is unable to return a value (e.g., if the server is unreachable and there is nothing cached). + +## off() + +Detaches a callback previously attached with the corresponding `on*()` (`onValue`, `onChildAdded`) listener. Note: This is not the recommended way to remove a listener. Instead, please use the returned callback function from the respective `on*` callbacks. + +Detach a callback previously attached with `on*()`. Calling `off()` on a parent listener will not automatically remove listeners registered on child nodes, `off()` must also be called on any child listeners to remove the callback. + +If a callback is not specified, all callbacks for the specified eventType will be removed. Similarly, if no eventType is specified, all callbacks for the `Reference` will be removed. + +Individual listeners can also be removed by invoking their unsubscribe callbacks. + +Signature: + +```typescript +export declare function off(query: Query, eventType?: EventType, callback?: (snapshot: DataSnapshot, previousChildName?: string | null) => unknown): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query that the listener was registered with. | +| eventType | [EventType](./database.md#eventtype) | One of the following strings: "value", "child\_added", "child\_changed", "child\_removed", or "child\_moved." If omitted, all callbacks for the Reference will be removed. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName?: string \| null) => unknown | The callback function that was passed to on() or undefined to remove all callbacks. | + +Returns: + +void + +## onChildAdded() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onChildAdded` event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The `DataSnapshot` passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. + +Signature: + +```typescript +export declare function onChildAdded(query: Query, callback: (snapshot: DataSnapshot, previousChildName?: string | null) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName?: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | +| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onChildAdded() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onChildAdded` event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The `DataSnapshot` passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. + +Signature: + +```typescript +export declare function onChildAdded(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, options: ListenOptions): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | +| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onChildAdded() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onChildAdded` event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The `DataSnapshot` passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. + +Signature: + +```typescript +export declare function onChildAdded(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | +| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | +| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onChildChanged() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onChildChanged` event will be triggered when the data stored in a child (or any of its descendants) changes. Note that a single `child_changed` event may represent multiple changes to the child. The `DataSnapshot` passed to the callback will contain the new child contents. For ordering purposes, the callback is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. + +Signature: + +```typescript +export declare function onChildChanged(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | +| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onChildChanged() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onChildChanged` event will be triggered when the data stored in a child (or any of its descendants) changes. Note that a single `child_changed` event may represent multiple changes to the child. The `DataSnapshot` passed to the callback will contain the new child contents. For ordering purposes, the callback is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. + +Signature: + +```typescript +export declare function onChildChanged(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, options: ListenOptions): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | +| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onChildChanged() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onChildChanged` event will be triggered when the data stored in a child (or any of its descendants) changes. Note that a single `child_changed` event may represent multiple changes to the child. The `DataSnapshot` passed to the callback will contain the new child contents. For ordering purposes, the callback is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. + +Signature: + +```typescript +export declare function onChildChanged(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | +| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | +| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onChildMoved() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onChildMoved` event will be triggered when a child's sort order changes such that its position relative to its siblings changes. The `DataSnapshot` passed to the callback will be for the data of the child that has moved. It is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. + +Signature: + +```typescript +export declare function onChildMoved(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | +| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onChildMoved() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onChildMoved` event will be triggered when a child's sort order changes such that its position relative to its siblings changes. The `DataSnapshot` passed to the callback will be for the data of the child that has moved. It is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. + +Signature: + +```typescript +export declare function onChildMoved(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, options: ListenOptions): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | +| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onChildMoved() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onChildMoved` event will be triggered when a child's sort order changes such that its position relative to its siblings changes. The `DataSnapshot` passed to the callback will be for the data of the child that has moved. It is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. + +Signature: + +```typescript +export declare function onChildMoved(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | +| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | +| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onChildRemoved() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onChildRemoved` event will be triggered once every time a child is removed. The `DataSnapshot` passed into the callback will be the old data for the child that was removed. A child will get removed when either: + +- a client explicitly calls `remove()` on that child or one of its ancestors - a client calls `set(null)` on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) + +Signature: + +```typescript +export declare function onChildRemoved(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | +| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onChildRemoved() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onChildRemoved` event will be triggered once every time a child is removed. The `DataSnapshot` passed into the callback will be the old data for the child that was removed. A child will get removed when either: + +- a client explicitly calls `remove()` on that child or one of its ancestors - a client calls `set(null)` on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) + +Signature: + +```typescript +export declare function onChildRemoved(query: Query, callback: (snapshot: DataSnapshot) => unknown, options: ListenOptions): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | +| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onChildRemoved() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onChildRemoved` event will be triggered once every time a child is removed. The `DataSnapshot` passed into the callback will be the old data for the child that was removed. A child will get removed when either: + +- a client explicitly calls `remove()` on that child or one of its ancestors - a client calls `set(null)` on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) + +Signature: + +```typescript +export declare function onChildRemoved(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | +| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | +| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onValue() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onValue` event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The `DataSnapshot` passed to the callback will be for the location at which `on()` was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty `DataSnapshot` (`val()` will return `null`). + +Signature: + +```typescript +export declare function onValue(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot. | +| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onValue() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onValue` event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The `DataSnapshot` passed to the callback will be for the location at which `on()` was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty `DataSnapshot` (`val()` will return `null`). + +Signature: + +```typescript +export declare function onValue(query: Query, callback: (snapshot: DataSnapshot) => unknown, options: ListenOptions): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot. | +| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onValue() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onValue` event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The `DataSnapshot` passed to the callback will be for the location at which `on()` was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty `DataSnapshot` (`val()` will return `null`). + +Signature: + +```typescript +export declare function onValue(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot. | +| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | +| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## query() + +Creates a new immutable instance of `Query` that is extended to also include additional query constraints. + +Signature: + +```typescript +export declare function query(query: Query, ...queryConstraints: QueryConstraint[]): Query; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The Query instance to use as a base for the new constraints. | +| queryConstraints | [QueryConstraint](./database.queryconstraint.md#queryconstraint_class)\[\] | The list of QueryConstraints to apply. | + +Returns: + +[Query](./database.query.md#query_interface) + +## Exceptions + +if any of the provided query constraints cannot be combined with the existing or new constraints. + +## onDisconnect() + +Returns an `OnDisconnect` object - see [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information on how to use it. + +Signature: + +```typescript +export declare function onDisconnect(ref: DatabaseReference): OnDisconnect; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The reference to add OnDisconnect triggers for. | + +Returns: + +[OnDisconnect](./database.ondisconnect.md#ondisconnect_class) + +## remove() + +Removes the data at this Database location. + +Any data at child locations will also be deleted. + +The effect of the remove will be visible immediately and the corresponding event 'value' will be triggered. Synchronization of the remove to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the onComplete callback will be called asynchronously after synchronization has finished. + +Signature: + +```typescript +export declare function remove(ref: DatabaseReference): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location to remove. | + +Returns: + +Promise<void> + +Resolves when remove on server is complete. + +## runTransaction() + +Atomically modifies the data at this location. + +Atomically modify the data at this location. Unlike a normal `set()`, which just overwrites the data regardless of its previous value, `runTransaction()` is used to modify the existing value to a new value, ensuring there are no conflicts with other clients writing to the same location at the same time. + +To accomplish this, you pass `runTransaction()` an update function which is used to transform the current value into a new value. If another client writes to the location before your new value is successfully written, your update function will be called again with the new current value, and the write will be retried. This will happen repeatedly until your write succeeds without conflict or you abort the transaction by not returning a value from your update function. + +Note: Modifying data with `set()` will cancel any pending transactions at that location, so extreme care should be taken if mixing `set()` and `runTransaction()` to update the same data. + +Note: When using transactions with Security and Firebase Rules in place, be aware that a client needs `.read` access in addition to `.write` access in order to perform a transaction. This is because the client-side nature of transactions requires the client to read the data in order to transactionally update it. + +Signature: + +```typescript +export declare function runTransaction(ref: DatabaseReference, transactionUpdate: (currentData: any) => unknown, options?: TransactionOptions): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location to atomically modify. | +| transactionUpdate | (currentData: any) => unknown | A developer-supplied function which will be passed the current data stored at this location (as a JavaScript object). The function should return the new value it would like written (as a JavaScript object). If undefined is returned (i.e. you return with no arguments) the transaction will be aborted and the data at this location will not be modified. | +| options | [TransactionOptions](./database.transactionoptions.md#transactionoptions_interface) | An options object to configure transactions. | + +Returns: + +Promise<[TransactionResult](./database.transactionresult.md#transactionresult_class)> + +A `Promise` that can optionally be used instead of the `onComplete` callback to handle success and failure. + +## set() + +Writes data to this Database location. + +This will overwrite any data at this location and all child locations. + +The effect of the write will be visible immediately, and the corresponding events ("value", "child\_added", etc.) will be triggered. Synchronization of the data to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the `onComplete` callback will be called asynchronously after synchronization has finished. + +Passing `null` for the new value is equivalent to calling `remove()`; namely, all data at this location and all child locations will be deleted. + +`set()` will remove any priority stored at this location, so if priority is meant to be preserved, you need to use `setWithPriority()` instead. + +Note that modifying data with `set()` will cancel any pending transactions at that location, so extreme care should be taken if mixing `set()` and `transaction()` to modify the same data. + +A single `set()` will generate a single "value" event at the location where the `set()` was performed. + +Signature: + +```typescript +export declare function set(ref: DatabaseReference, value: unknown): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location to write to. | +| value | unknown | The value to be written (string, number, boolean, object, array, or null). | + +Returns: + +Promise<void> + +Resolves when write to server is complete. + +## setPriority() + +Sets a priority for the data at this Database location. + +Applications need not use priority but can order collections by ordinary properties (see [Sorting and filtering data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) ). + +Signature: + +```typescript +export declare function setPriority(ref: DatabaseReference, priority: string | number | null): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location to write to. | +| priority | string \| number \| null | The priority to be written (string, number, or null). | + +Returns: + +Promise<void> + +Resolves when write to server is complete. + +## setWithPriority() + +Writes data the Database location. Like `set()` but also specifies the priority for that data. + +Applications need not use priority but can order collections by ordinary properties (see [Sorting and filtering data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) ). + +Signature: + +```typescript +export declare function setWithPriority(ref: DatabaseReference, value: unknown, priority: string | number | null): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location to write to. | +| value | unknown | The value to be written (string, number, boolean, object, array, or null). | +| priority | string \| number \| null | The priority to be written (string, number, or null). | + +Returns: + +Promise<void> + +Resolves when write to server is complete. + +## update() + +Writes multiple values to the Database at once. + +The `values` argument contains multiple property-value pairs that will be written to the Database together. Each child property can either be a simple property (for example, "name") or a relative path (for example, "name/first") from the current location to the data to update. + +As opposed to the `set()` method, `update()` can be use to selectively update only the referenced properties at the current location (instead of replacing all the child properties at the current location). + +The effect of the write will be visible immediately, and the corresponding events ('value', 'child\_added', etc.) will be triggered. Synchronization of the data to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the `onComplete` callback will be called asynchronously after synchronization has finished. + +A single `update()` will generate a single "value" event at the location where the `update()` was performed, regardless of how many children were modified. + +Note that modifying data with `update()` will cancel any pending transactions at that location, so extreme care should be taken if mixing `update()` and `transaction()` to modify the same data. + +Passing `null` to `update()` will remove the data at this location. + +See [Introducing multi-location updates and more](https://firebase.googleblog.com/2015/09/introducing-multi-location-updates-and_86.html). + +Signature: + +```typescript +export declare function update(ref: DatabaseReference, values: object): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location to write to. | +| values | object | Object containing multiple values. | + +Returns: + +Promise<void> + +Resolves when update on server is complete. + +## endAt() + +Creates a `QueryConstraint` with the specified ending point. + +Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. + +The ending point is inclusive, so children with exactly the specified value will be included in the query. The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have a key name less than or equal to the specified key. + +You can read more about `endAt()` in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). + +Signature: + +```typescript +export declare function endAt(value: number | string | boolean | null, key?: string): QueryConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| value | number \| string \| boolean \| null | The value to end at. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | +| key | string | The child key to end at, among the children with the previously specified priority. This argument is only allowed if ordering by child, value, or priority. | + +Returns: + +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) + +## endBefore() + +Creates a `QueryConstraint` with the specified ending point (exclusive). + +Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. + +The ending point is exclusive. If only a value is provided, children with a value less than the specified value will be included in the query. If a key is specified, then children must have a value less than or equal to the specified value and a key name less than the specified key. + +Signature: + +```typescript +export declare function endBefore(value: number | string | boolean | null, key?: string): QueryConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| value | number \| string \| boolean \| null | The value to end before. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | +| key | string | The child key to end before, among the children with the previously specified priority. This argument is only allowed if ordering by child, value, or priority. | + +Returns: + +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) + +## equalTo() + +Creates a `QueryConstraint` that includes children that match the specified value. + +Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. + +The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have exactly the specified key as their key name. This can be used to filter result sets with many matches for the same value. + +You can read more about `equalTo()` in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). + +Signature: + +```typescript +export declare function equalTo(value: number | string | boolean | null, key?: string): QueryConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| value | number \| string \| boolean \| null | The value to match for. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | +| key | string | The child key to start at, among the children with the previously specified priority. This argument is only allowed if ordering by child, value, or priority. | + +Returns: + +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) + +## startAfter() + +Creates a `QueryConstraint` with the specified starting point (exclusive). + +Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. + +The starting point is exclusive. If only a value is provided, children with a value greater than the specified value will be included in the query. If a key is specified, then children must have a value greater than or equal to the specified value and a a key name greater than the specified key. + +Signature: + +```typescript +export declare function startAfter(value: number | string | boolean | null, key?: string): QueryConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| value | number \| string \| boolean \| null | The value to start after. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | +| key | string | The child key to start after. This argument is only allowed if ordering by child, value, or priority. | + +Returns: + +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) + +## startAt() + +Creates a `QueryConstraint` with the specified starting point. + +Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. + +The starting point is inclusive, so children with exactly the specified value will be included in the query. The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have a key name greater than or equal to the specified key. + +You can read more about `startAt()` in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). + +Signature: + +```typescript +export declare function startAt(value?: number | string | boolean | null, key?: string): QueryConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| value | number \| string \| boolean \| null | The value to start at. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | +| key | string | The child key to start at. This argument is only allowed if ordering by child, value, or priority. | + +Returns: + +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) + +## EventType + +One of the following strings: "value", "child\_added", "child\_changed", "child\_removed", or "child\_moved." + +Signature: + +```typescript +export declare type EventType = 'value' | 'child_added' | 'child_changed' | 'child_moved' | 'child_removed'; +``` + +## QueryConstraintType + +Describes the different query constraints available in this SDK. + +Signature: + +```typescript +export declare type QueryConstraintType = 'endAt' | 'endBefore' | 'startAt' | 'startAfter' | 'limitToFirst' | 'limitToLast' | 'orderByChild' | 'orderByKey' | 'orderByPriority' | 'orderByValue' | 'equalTo'; +``` + +## Unsubscribe + +A callback that can invoked to remove a listener. + +Signature: + +```typescript +export declare type Unsubscribe = () => void; +``` diff --git a/docs-devsite/database.ondisconnect.md b/docs-devsite/database.ondisconnect.md new file mode 100644 index 00000000000..b7ed5075365 --- /dev/null +++ b/docs-devsite/database.ondisconnect.md @@ -0,0 +1,143 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# OnDisconnect class +The `onDisconnect` class allows you to write or clear data when your client disconnects from the Database server. These updates occur whether your client disconnects cleanly or not, so you can rely on them to clean up data even if a connection is dropped or a client crashes. + +The `onDisconnect` class is most commonly used to manage presence in applications where it is useful to detect how many clients are connected and when other clients disconnect. See [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information. + +To avoid problems when a connection is dropped before the requests can be transferred to the Database server, these functions should be called before writing any data. + +Note that `onDisconnect` operations are only triggered once. If you want an operation to occur each time a disconnect occurs, you'll need to re-establish the `onDisconnect` operations each time you reconnect. + +Signature: + +```typescript +export declare class OnDisconnect +``` + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [cancel()](./database.ondisconnect.md#ondisconnectcancel) | | Cancels all previously queued onDisconnect() set or update events for this location and all children.If a write has been queued for this location via a set() or update() at a parent location, the write at this location will be canceled, though writes to sibling locations will still occur. | +| [remove()](./database.ondisconnect.md#ondisconnectremove) | | Ensures the data at this location is deleted when the client is disconnected (due to closing the browser, navigating to a new page, or network issues). | +| [set(value)](./database.ondisconnect.md#ondisconnectset) | | Ensures the data at this location is set to the specified value when the client is disconnected (due to closing the browser, navigating to a new page, or network issues).set() is especially useful for implementing "presence" systems, where a value should be changed or cleared when a user disconnects so that they appear "offline" to other users. See [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information.Note that onDisconnect operations are only triggered once. If you want an operation to occur each time a disconnect occurs, you'll need to re-establish the onDisconnect operations each time. | +| [setWithPriority(value, priority)](./database.ondisconnect.md#ondisconnectsetwithpriority) | | Ensures the data at this location is set to the specified value and priority when the client is disconnected (due to closing the browser, navigating to a new page, or network issues). | +| [update(values)](./database.ondisconnect.md#ondisconnectupdate) | | Writes multiple values at this location when the client is disconnected (due to closing the browser, navigating to a new page, or network issues).The values argument contains multiple property-value pairs that will be written to the Database together. Each child property can either be a simple property (for example, "name") or a relative path (for example, "name/first") from the current location to the data to update.As opposed to the set() method, update() can be use to selectively update only the referenced properties at the current location (instead of replacing all the child properties at the current location). | + +## OnDisconnect.cancel() + +Cancels all previously queued `onDisconnect()` set or update events for this location and all children. + +If a write has been queued for this location via a `set()` or `update()` at a parent location, the write at this location will be canceled, though writes to sibling locations will still occur. + +Signature: + +```typescript +cancel(): Promise; +``` +Returns: + +Promise<void> + +Resolves when synchronization to the server is complete. + +## OnDisconnect.remove() + +Ensures the data at this location is deleted when the client is disconnected (due to closing the browser, navigating to a new page, or network issues). + +Signature: + +```typescript +remove(): Promise; +``` +Returns: + +Promise<void> + +Resolves when synchronization to the server is complete. + +## OnDisconnect.set() + +Ensures the data at this location is set to the specified value when the client is disconnected (due to closing the browser, navigating to a new page, or network issues). + +`set()` is especially useful for implementing "presence" systems, where a value should be changed or cleared when a user disconnects so that they appear "offline" to other users. See [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information. + +Note that `onDisconnect` operations are only triggered once. If you want an operation to occur each time a disconnect occurs, you'll need to re-establish the `onDisconnect` operations each time. + +Signature: + +```typescript +set(value: unknown): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| value | unknown | The value to be written to this location on disconnect (can be an object, array, string, number, boolean, or null). | + +Returns: + +Promise<void> + +Resolves when synchronization to the Database is complete. + +## OnDisconnect.setWithPriority() + +Ensures the data at this location is set to the specified value and priority when the client is disconnected (due to closing the browser, navigating to a new page, or network issues). + +Signature: + +```typescript +setWithPriority(value: unknown, priority: number | string | null): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| value | unknown | The value to be written to this location on disconnect (can be an object, array, string, number, boolean, or null). | +| priority | number \| string \| null | The priority to be written (string, number, or null). | + +Returns: + +Promise<void> + +Resolves when synchronization to the Database is complete. + +## OnDisconnect.update() + +Writes multiple values at this location when the client is disconnected (due to closing the browser, navigating to a new page, or network issues). + +The `values` argument contains multiple property-value pairs that will be written to the Database together. Each child property can either be a simple property (for example, "name") or a relative path (for example, "name/first") from the current location to the data to update. + +As opposed to the `set()` method, `update()` can be use to selectively update only the referenced properties at the current location (instead of replacing all the child properties at the current location). + +Signature: + +```typescript +update(values: object): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| values | object | Object containing multiple values. | + +Returns: + +Promise<void> + +Resolves when synchronization to the Database is complete. + diff --git a/docs-devsite/database.query.md b/docs-devsite/database.query.md new file mode 100644 index 00000000000..8ef7b8f8e46 --- /dev/null +++ b/docs-devsite/database.query.md @@ -0,0 +1,108 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Query interface +A `Query` sorts and filters the data at a Database location so only a subset of the child data is included. This can be used to order a collection of data by some attribute (for example, height of dinosaurs) as well as to restrict a large list of items (for example, chat messages) down to a number suitable for synchronizing to the client. Queries are created by chaining together one or more of the filter methods defined here. + +Just as with a `DatabaseReference`, you can receive data from a `Query` by using the `on*()` methods. You will only receive events and `DataSnapshot`s for the subset of the data that matches your query. + +See [https://firebase.google.com/docs/database/web/lists-of-data\#sorting\_and\_filtering\_data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) for more information. + +Signature: + +```typescript +export declare interface Query +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [ref](./database.query.md#queryref) | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The DatabaseReference for the Query's location. | + +## Methods + +| Method | Description | +| --- | --- | +| [isEqual(other)](./database.query.md#queryisequal) | Returns whether or not the current and provided queries represent the same location, have the same query parameters, and are from the same instance of FirebaseApp.Two DatabaseReference objects are equivalent if they represent the same location and are from the same instance of FirebaseApp.Two Query objects are equivalent if they represent the same location, have the same query parameters, and are from the same instance of FirebaseApp. Equivalent queries share the same sort order, limits, and starting and ending points. | +| [toJSON()](./database.query.md#querytojson) | Returns a JSON-serializable representation of this object. | +| [toString()](./database.query.md#querytostring) | Gets the absolute URL for this location.The toString() method returns a URL that is ready to be put into a browser, curl command, or a refFromURL() call. Since all of those expect the URL to be url-encoded, toString() returns an encoded URL.Append '.json' to the returned URL when typed into a browser to download JSON-formatted data. If the location is secured (that is, not publicly readable), you will get a permission-denied error. | + +## Query.ref + +The `DatabaseReference` for the `Query`'s location. + +Signature: + +```typescript +readonly ref: DatabaseReference; +``` + +## Query.isEqual() + +Returns whether or not the current and provided queries represent the same location, have the same query parameters, and are from the same instance of `FirebaseApp`. + +Two `DatabaseReference` objects are equivalent if they represent the same location and are from the same instance of `FirebaseApp`. + +Two `Query` objects are equivalent if they represent the same location, have the same query parameters, and are from the same instance of `FirebaseApp`. Equivalent queries share the same sort order, limits, and starting and ending points. + +Signature: + +```typescript +isEqual(other: Query | null): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| other | [Query](./database.query.md#query_interface) \| null | The query to compare against. | + +Returns: + +boolean + +Whether or not the current and provided queries are equivalent. + +## Query.toJSON() + +Returns a JSON-serializable representation of this object. + +Signature: + +```typescript +toJSON(): string; +``` +Returns: + +string + +A JSON-serializable representation of this object. + +## Query.toString() + +Gets the absolute URL for this location. + +The `toString()` method returns a URL that is ready to be put into a browser, curl command, or a `refFromURL()` call. Since all of those expect the URL to be url-encoded, `toString()` returns an encoded URL. + +Append '.json' to the returned URL when typed into a browser to download JSON-formatted data. If the location is secured (that is, not publicly readable), you will get a permission-denied error. + +Signature: + +```typescript +toString(): string; +``` +Returns: + +string + +The absolute URL for this location. + diff --git a/docs-devsite/database.queryconstraint.md b/docs-devsite/database.queryconstraint.md new file mode 100644 index 00000000000..fe98c6badf3 --- /dev/null +++ b/docs-devsite/database.queryconstraint.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryConstraint class +A `QueryConstraint` is used to narrow the set of documents returned by a Database query. `QueryConstraint`s are created by invoking [endAt()](./database.md#endat), [endBefore()](./database.md#endbefore), [startAt()](./database.md#startat), [startAfter()](./database.md#startafter), [limitToFirst()](./database.md#limittofirst), [limitToLast()](./database.md#limittolast), [orderByChild()](./database.md#orderbychild), [orderByChild()](./database.md#orderbychild), [orderByKey()](./database.md#orderbykey) , [orderByPriority()](./database.md#orderbypriority) , [orderByValue()](./database.md#orderbyvalue) or [equalTo()](./database.md#equalto) and can then be passed to [query()](./database.md#query) to create a new query instance that also contains this `QueryConstraint`. + +Signature: + +```typescript +export declare abstract class QueryConstraint +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./database.queryconstraint.md#queryconstrainttype) | | [QueryConstraintType](./database.md#queryconstrainttype) | The type of this query constraints | + +## QueryConstraint.type + +The type of this query constraints + +Signature: + +```typescript +abstract readonly type: QueryConstraintType; +``` diff --git a/docs-devsite/database.thenablereference.md b/docs-devsite/database.thenablereference.md new file mode 100644 index 00000000000..b6231d2bd03 --- /dev/null +++ b/docs-devsite/database.thenablereference.md @@ -0,0 +1,21 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ThenableReference interface +A `Promise` that can also act as a `DatabaseReference` when returned by [push()](./database.md#push). The reference is available immediately and the `Promise` resolves as the write to the backend completes. + +Signature: + +```typescript +export declare interface ThenableReference extends DatabaseReference, Pick, 'then' | 'catch'> +``` +Extends: [DatabaseReference](./database.databasereference.md#databasereference_interface), Pick<Promise<[DatabaseReference](./database.databasereference.md#databasereference_interface)>, 'then' \| 'catch'> + diff --git a/docs-devsite/database.transactionoptions.md b/docs-devsite/database.transactionoptions.md new file mode 100644 index 00000000000..0dee85c3a99 --- /dev/null +++ b/docs-devsite/database.transactionoptions.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# TransactionOptions interface +An options object to configure transactions. + +Signature: + +```typescript +export declare interface TransactionOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [applyLocally](./database.transactionoptions.md#transactionoptionsapplylocally) | boolean | By default, events are raised each time the transaction update function runs. So if it is run multiple times, you may see intermediate states. You can set this to false to suppress these intermediate states and instead wait until the transaction has completed before events are raised. | + +## TransactionOptions.applyLocally + +By default, events are raised each time the transaction update function runs. So if it is run multiple times, you may see intermediate states. You can set this to false to suppress these intermediate states and instead wait until the transaction has completed before events are raised. + +Signature: + +```typescript +readonly applyLocally?: boolean; +``` diff --git a/docs-devsite/database.transactionresult.md b/docs-devsite/database.transactionresult.md new file mode 100644 index 00000000000..aad84fd6a6b --- /dev/null +++ b/docs-devsite/database.transactionresult.md @@ -0,0 +1,66 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# TransactionResult class +A type for the resolve value of [runTransaction()](./database.md#runtransaction). + +Signature: + +```typescript +export declare class TransactionResult +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [committed](./database.transactionresult.md#transactionresultcommitted) | | boolean | Whether the transaction was successfully committed. | +| [snapshot](./database.transactionresult.md#transactionresultsnapshot) | | [DataSnapshot](./database.datasnapshot.md#datasnapshot_class) | The resulting data snapshot. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [toJSON()](./database.transactionresult.md#transactionresulttojson) | | Returns a JSON-serializable representation of this object. | + +## TransactionResult.committed + +Whether the transaction was successfully committed. + +Signature: + +```typescript +readonly committed: boolean; +``` + +## TransactionResult.snapshot + +The resulting data snapshot. + +Signature: + +```typescript +readonly snapshot: DataSnapshot; +``` + +## TransactionResult.toJSON() + +Returns a JSON-serializable representation of this object. + +Signature: + +```typescript +toJSON(): object; +``` +Returns: + +object + diff --git a/docs-devsite/firestore.md b/docs-devsite/firestore.md new file mode 100644 index 00000000000..c8c647cf611 --- /dev/null +++ b/docs-devsite/firestore.md @@ -0,0 +1,19 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# firestore package +Cloud Firestore + +| Entry Point | Description | +| --- | --- | +| [/](./firestore_.md#@firebase/firestore) | | +| [/lite](./firestore_lite.md#@firebase/firestore/lite) | | + diff --git a/docs-devsite/firestore_.aggregatefield.md b/docs-devsite/firestore_.aggregatefield.md new file mode 100644 index 00000000000..0c3957520b3 --- /dev/null +++ b/docs-devsite/firestore_.aggregatefield.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AggregateField class +Represents an aggregation that can be performed by Firestore. + +Signature: + +```typescript +export declare class AggregateField +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_.aggregatefield.md#aggregatefieldtype) | | string | A type string to uniquely identify instances of this class. | + +## AggregateField.type + +A type string to uniquely identify instances of this class. + +Signature: + +```typescript +type: string; +``` diff --git a/docs-devsite/firestore_.aggregatequerysnapshot.md b/docs-devsite/firestore_.aggregatequerysnapshot.md new file mode 100644 index 00000000000..1cf63b5db8b --- /dev/null +++ b/docs-devsite/firestore_.aggregatequerysnapshot.md @@ -0,0 +1,70 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AggregateQuerySnapshot class +The results of executing an aggregation query. + +Signature: + +```typescript +export declare class AggregateQuerySnapshot +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [query](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshotquery) | | [Query](./firestore_.query.md#query_class)<unknown> | The underlying query over which the aggregations recorded in this AggregateQuerySnapshot were performed. | +| [type](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshottype) | | (not declared) | A type string to uniquely identify instances of this class. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [data()](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshotdata) | | Returns the results of the aggregations performed over the underlying query.The keys of the returned object will be the same as those of the AggregateSpec object specified to the aggregation method, and the values will be the corresponding aggregation result. | + +## AggregateQuerySnapshot.query + +The underlying query over which the aggregations recorded in this `AggregateQuerySnapshot` were performed. + +Signature: + +```typescript +readonly query: Query; +``` + +## AggregateQuerySnapshot.type + +A type string to uniquely identify instances of this class. + +Signature: + +```typescript +readonly type = "AggregateQuerySnapshot"; +``` + +## AggregateQuerySnapshot.data() + +Returns the results of the aggregations performed over the underlying query. + +The keys of the returned object will be the same as those of the `AggregateSpec` object specified to the aggregation method, and the values will be the corresponding aggregation result. + +Signature: + +```typescript +data(): AggregateSpecData; +``` +Returns: + +[AggregateSpecData](./firestore_.md#aggregatespecdata)<T> + +The results of the aggregations performed over the underlying query. + diff --git a/docs-devsite/firestore_.aggregatespec.md b/docs-devsite/firestore_.aggregatespec.md new file mode 100644 index 00000000000..be06b6941f3 --- /dev/null +++ b/docs-devsite/firestore_.aggregatespec.md @@ -0,0 +1,19 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AggregateSpec interface +A type whose property values are all `AggregateField` objects. + +Signature: + +```typescript +export declare interface AggregateSpec +``` diff --git a/docs-devsite/firestore_.bytes.md b/docs-devsite/firestore_.bytes.md new file mode 100644 index 00000000000..411abe327c5 --- /dev/null +++ b/docs-devsite/firestore_.bytes.md @@ -0,0 +1,138 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Bytes class +An immutable object representing an array of bytes. + +Signature: + +```typescript +export declare class Bytes +``` + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [fromBase64String(base64)](./firestore_.bytes.md#bytesfrombase64string) | static | Creates a new Bytes object from the given Base64 string, converting it to bytes. | +| [fromUint8Array(array)](./firestore_.bytes.md#bytesfromuint8array) | static | Creates a new Bytes object from the given Uint8Array. | +| [isEqual(other)](./firestore_.bytes.md#bytesisequal) | | Returns true if this Bytes object is equal to the provided one. | +| [toBase64()](./firestore_.bytes.md#bytestobase64) | | Returns the underlying bytes as a Base64-encoded string. | +| [toString()](./firestore_.bytes.md#bytestostring) | | Returns a string representation of the Bytes object. | +| [toUint8Array()](./firestore_.bytes.md#bytestouint8array) | | Returns the underlying bytes in a new Uint8Array. | + +## Bytes.fromBase64String() + +Creates a new `Bytes` object from the given Base64 string, converting it to bytes. + +Signature: + +```typescript +static fromBase64String(base64: string): Bytes; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| base64 | string | The Base64 string used to create the Bytes object. | + +Returns: + +[Bytes](./firestore_.bytes.md#bytes_class) + +## Bytes.fromUint8Array() + +Creates a new `Bytes` object from the given Uint8Array. + +Signature: + +```typescript +static fromUint8Array(array: Uint8Array): Bytes; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| array | Uint8Array | The Uint8Array used to create the Bytes object. | + +Returns: + +[Bytes](./firestore_.bytes.md#bytes_class) + +## Bytes.isEqual() + +Returns true if this `Bytes` object is equal to the provided one. + +Signature: + +```typescript +isEqual(other: Bytes): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| other | [Bytes](./firestore_.bytes.md#bytes_class) | The Bytes object to compare against. | + +Returns: + +boolean + +true if this `Bytes` object is equal to the provided one. + +## Bytes.toBase64() + +Returns the underlying bytes as a Base64-encoded string. + +Signature: + +```typescript +toBase64(): string; +``` +Returns: + +string + +The Base64-encoded string created from the `Bytes` object. + +## Bytes.toString() + +Returns a string representation of the `Bytes` object. + +Signature: + +```typescript +toString(): string; +``` +Returns: + +string + +A string representation of the `Bytes` object. + +## Bytes.toUint8Array() + +Returns the underlying bytes in a new `Uint8Array`. + +Signature: + +```typescript +toUint8Array(): Uint8Array; +``` +Returns: + +Uint8Array + +The Uint8Array created from the `Bytes` object. + diff --git a/docs-devsite/firestore_.collectionreference.md b/docs-devsite/firestore_.collectionreference.md new file mode 100644 index 00000000000..56c81c6b245 --- /dev/null +++ b/docs-devsite/firestore_.collectionreference.md @@ -0,0 +1,121 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# CollectionReference class +A `CollectionReference` object can be used for adding documents, getting document references, and querying for documents (using [query()](./firestore_.md#query)). + +Signature: + +```typescript +export declare class CollectionReference extends Query +``` +Extends: [Query](./firestore_.query.md#query_class)<T> + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [id](./firestore_.collectionreference.md#collectionreferenceid) | | string | The collection's identifier. | +| [parent](./firestore_.collectionreference.md#collectionreferenceparent) | | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> \| null | A reference to the containing DocumentReference if this is a subcollection. If this isn't a subcollection, the reference is null. | +| [path](./firestore_.collectionreference.md#collectionreferencepath) | | string | A string representing the path of the referenced collection (relative to the root of the database). | +| [type](./firestore_.collectionreference.md#collectionreferencetype) | | (not declared) | The type of this Firestore reference. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [withConverter(converter)](./firestore_.collectionreference.md#collectionreferencewithconverter) | | Applies a custom data converter to this CollectionReference, allowing you to use your own custom model objects with Firestore. When you call [addDoc()](./firestore_.md#adddoc) with the returned CollectionReference instance, the provided converter will convert between Firestore data and your custom type U. | +| [withConverter(converter)](./firestore_.collectionreference.md#collectionreferencewithconverter) | | Removes the current converter. | + +## CollectionReference.id + +The collection's identifier. + +Signature: + +```typescript +get id(): string; +``` + +## CollectionReference.parent + +A reference to the containing `DocumentReference` if this is a subcollection. If this isn't a subcollection, the reference is null. + +Signature: + +```typescript +get parent(): DocumentReference | null; +``` + +## CollectionReference.path + +A string representing the path of the referenced collection (relative to the root of the database). + +Signature: + +```typescript +get path(): string; +``` + +## CollectionReference.type + +The type of this Firestore reference. + +Signature: + +```typescript +readonly type = "collection"; +``` + +## CollectionReference.withConverter() + +Applies a custom data converter to this `CollectionReference`, allowing you to use your own custom model objects with Firestore. When you call [addDoc()](./firestore_.md#adddoc) with the returned `CollectionReference` instance, the provided converter will convert between Firestore data and your custom type `U`. + +Signature: + +```typescript +withConverter(converter: FirestoreDataConverter): CollectionReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| converter | [FirestoreDataConverter](./firestore_.firestoredataconverter.md#firestoredataconverter_interface)<U> | Converts objects to and from Firestore. | + +Returns: + +[CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<U> + +A `CollectionReference` that uses the provided converter. + +## CollectionReference.withConverter() + +Removes the current converter. + +Signature: + +```typescript +withConverter(converter: null): CollectionReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| converter | null | null removes the current converter. | + +Returns: + +[CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> + +A `CollectionReference` that does not use a converter. + diff --git a/docs-devsite/firestore_.documentchange.md b/docs-devsite/firestore_.documentchange.md new file mode 100644 index 00000000000..afef795956d --- /dev/null +++ b/docs-devsite/firestore_.documentchange.md @@ -0,0 +1,68 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# DocumentChange interface +A `DocumentChange` represents a change to the documents matching a query. It contains the document affected and the type of change that occurred. + +Signature: + +```typescript +export declare interface DocumentChange +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [doc](./firestore_.documentchange.md#documentchangedoc) | [QueryDocumentSnapshot](./firestore_.querydocumentsnapshot.md#querydocumentsnapshot_class)<T> | The document affected by this change. | +| [newIndex](./firestore_.documentchange.md#documentchangenewindex) | number | The index of the changed document in the result set immediately after this DocumentChange (i.e. supposing that all prior DocumentChange objects and the current DocumentChange object have been applied). Is -1 for 'removed' events. | +| [oldIndex](./firestore_.documentchange.md#documentchangeoldindex) | number | The index of the changed document in the result set immediately prior to this DocumentChange (i.e. supposing that all prior DocumentChange objects have been applied). Is -1 for 'added' events. | +| [type](./firestore_.documentchange.md#documentchangetype) | [DocumentChangeType](./firestore_.md#documentchangetype) | The type of change ('added', 'modified', or 'removed'). | + +## DocumentChange.doc + +The document affected by this change. + +Signature: + +```typescript +readonly doc: QueryDocumentSnapshot; +``` + +## DocumentChange.newIndex + +The index of the changed document in the result set immediately after this `DocumentChange` (i.e. supposing that all prior `DocumentChange` objects and the current `DocumentChange` object have been applied). Is -1 for 'removed' events. + +Signature: + +```typescript +readonly newIndex: number; +``` + +## DocumentChange.oldIndex + +The index of the changed document in the result set immediately prior to this `DocumentChange` (i.e. supposing that all prior `DocumentChange` objects have been applied). Is `-1` for 'added' events. + +Signature: + +```typescript +readonly oldIndex: number; +``` + +## DocumentChange.type + +The type of change ('added', 'modified', or 'removed'). + +Signature: + +```typescript +readonly type: DocumentChangeType; +``` diff --git a/docs-devsite/firestore_.documentdata.md b/docs-devsite/firestore_.documentdata.md new file mode 100644 index 00000000000..09b5eb64b48 --- /dev/null +++ b/docs-devsite/firestore_.documentdata.md @@ -0,0 +1,19 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# DocumentData interface +Document data (for use with [setDoc()](./firestore_lite.md#setdoc)) consists of fields mapped to values. + +Signature: + +```typescript +export declare interface DocumentData +``` diff --git a/docs-devsite/firestore_.documentreference.md b/docs-devsite/firestore_.documentreference.md new file mode 100644 index 00000000000..16dff93b9c8 --- /dev/null +++ b/docs-devsite/firestore_.documentreference.md @@ -0,0 +1,142 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# DocumentReference class +A `DocumentReference` refers to a document location in a Firestore database and can be used to write, read, or listen to the location. The document at the referenced location may or may not exist. + +Signature: + +```typescript +export declare class DocumentReference +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [converter](./firestore_.documentreference.md#documentreferenceconverter) | | [FirestoreDataConverter](./firestore_.firestoredataconverter.md#firestoredataconverter_interface)<T> \| null | If provided, the FirestoreDataConverter associated with this instance. | +| [firestore](./firestore_.documentreference.md#documentreferencefirestore) | | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance the document is in. This is useful for performing transactions, for example. | +| [id](./firestore_.documentreference.md#documentreferenceid) | | string | The document's identifier within its collection. | +| [parent](./firestore_.documentreference.md#documentreferenceparent) | | [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | The collection this DocumentReference belongs to. | +| [path](./firestore_.documentreference.md#documentreferencepath) | | string | A string representing the path of the referenced document (relative to the root of the database). | +| [type](./firestore_.documentreference.md#documentreferencetype) | | (not declared) | The type of this Firestore reference. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [withConverter(converter)](./firestore_.documentreference.md#documentreferencewithconverter) | | Applies a custom data converter to this DocumentReference, allowing you to use your own custom model objects with Firestore. When you call [setDoc()](./firestore_lite.md#setdoc), [getDoc()](./firestore_lite.md#getdoc), etc. with the returned DocumentReference instance, the provided converter will convert between Firestore data and your custom type U. | +| [withConverter(converter)](./firestore_.documentreference.md#documentreferencewithconverter) | | Removes the current converter. | + +## DocumentReference.converter + +If provided, the `FirestoreDataConverter` associated with this instance. + +Signature: + +```typescript +readonly converter: FirestoreDataConverter | null; +``` + +## DocumentReference.firestore + +The [Firestore](./firestore_.firestore.md#firestore_class) instance the document is in. This is useful for performing transactions, for example. + +Signature: + +```typescript +readonly firestore: Firestore; +``` + +## DocumentReference.id + +The document's identifier within its collection. + +Signature: + +```typescript +get id(): string; +``` + +## DocumentReference.parent + +The collection this `DocumentReference` belongs to. + +Signature: + +```typescript +get parent(): CollectionReference; +``` + +## DocumentReference.path + +A string representing the path of the referenced document (relative to the root of the database). + +Signature: + +```typescript +get path(): string; +``` + +## DocumentReference.type + +The type of this Firestore reference. + +Signature: + +```typescript +readonly type = "document"; +``` + +## DocumentReference.withConverter() + +Applies a custom data converter to this `DocumentReference`, allowing you to use your own custom model objects with Firestore. When you call [setDoc()](./firestore_lite.md#setdoc), [getDoc()](./firestore_lite.md#getdoc), etc. with the returned `DocumentReference` instance, the provided converter will convert between Firestore data and your custom type `U`. + +Signature: + +```typescript +withConverter(converter: FirestoreDataConverter): DocumentReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| converter | [FirestoreDataConverter](./firestore_.firestoredataconverter.md#firestoredataconverter_interface)<U> | Converts objects to and from Firestore. | + +Returns: + +[DocumentReference](./firestore_.documentreference.md#documentreference_class)<U> + +A `DocumentReference` that uses the provided converter. + +## DocumentReference.withConverter() + +Removes the current converter. + +Signature: + +```typescript +withConverter(converter: null): DocumentReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| converter | null | null removes the current converter. | + +Returns: + +[DocumentReference](./firestore_.documentreference.md#documentreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> + +A `DocumentReference` that does not use a converter. + diff --git a/docs-devsite/firestore_.documentsnapshot.md b/docs-devsite/firestore_.documentsnapshot.md new file mode 100644 index 00000000000..3ac2ec7dcb2 --- /dev/null +++ b/docs-devsite/firestore_.documentsnapshot.md @@ -0,0 +1,146 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# DocumentSnapshot class +A `DocumentSnapshot` contains data read from a document in your Firestore database. The data can be extracted with `.data()` or `.get()` to get a specific field. + +For a `DocumentSnapshot` that points to a non-existing document, any data access will return 'undefined'. You can use the `exists()` method to explicitly verify a document's existence. + +Signature: + +```typescript +export declare class DocumentSnapshot +``` + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)()](./firestore_.documentsnapshot.md#documentsnapshotconstructor) | | Constructs a new instance of the DocumentSnapshot class | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [id](./firestore_.documentsnapshot.md#documentsnapshotid) | | string | Property of the DocumentSnapshot that provides the document's ID. | +| [metadata](./firestore_.documentsnapshot.md#documentsnapshotmetadata) | | [SnapshotMetadata](./firestore_.snapshotmetadata.md#snapshotmetadata_class) | Metadata about the DocumentSnapshot, including information about its source and local modifications. | +| [ref](./firestore_.documentsnapshot.md#documentsnapshotref) | | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | The DocumentReference for the document included in the DocumentSnapshot. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [data(options)](./firestore_.documentsnapshot.md#documentsnapshotdata) | | Retrieves all fields in the document as an Object. Returns undefined if the document doesn't exist.By default, serverTimestamp() values that have not yet been set to their final value will be returned as null. You can override this by passing an options object. | +| [exists()](./firestore_.documentsnapshot.md#documentsnapshotexists) | | Returns whether or not the data exists. True if the document exists. | +| [get(fieldPath, options)](./firestore_.documentsnapshot.md#documentsnapshotget) | | Retrieves the field specified by fieldPath. Returns undefined if the document or field doesn't exist.By default, a serverTimestamp() that has not yet been set to its final value will be returned as null. You can override this by passing an options object. | + +## DocumentSnapshot.(constructor) + +Constructs a new instance of the `DocumentSnapshot` class + +Signature: + +```typescript +protected constructor(); +``` + +## DocumentSnapshot.id + +Property of the `DocumentSnapshot` that provides the document's ID. + +Signature: + +```typescript +get id(): string; +``` + +## DocumentSnapshot.metadata + +Metadata about the `DocumentSnapshot`, including information about its source and local modifications. + +Signature: + +```typescript +readonly metadata: SnapshotMetadata; +``` + +## DocumentSnapshot.ref + +The `DocumentReference` for the document included in the `DocumentSnapshot`. + +Signature: + +```typescript +get ref(): DocumentReference; +``` + +## DocumentSnapshot.data() + +Retrieves all fields in the document as an `Object`. Returns `undefined` if the document doesn't exist. + +By default, `serverTimestamp()` values that have not yet been set to their final value will be returned as `null`. You can override this by passing an options object. + +Signature: + +```typescript +data(options?: SnapshotOptions): T | undefined; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| options | [SnapshotOptions](./firestore_.snapshotoptions.md#snapshotoptions_interface) | An options object to configure how data is retrieved from the snapshot (for example the desired behavior for server timestamps that have not yet been set to their final value). | + +Returns: + +T \| undefined + +An `Object` containing all fields in the document or `undefined` if the document doesn't exist. + +## DocumentSnapshot.exists() + +Returns whether or not the data exists. True if the document exists. + +Signature: + +```typescript +exists(): this is QueryDocumentSnapshot; +``` +Returns: + +this is [QueryDocumentSnapshot](./firestore_.querydocumentsnapshot.md#querydocumentsnapshot_class)<T> + +## DocumentSnapshot.get() + +Retrieves the field specified by `fieldPath`. Returns `undefined` if the document or field doesn't exist. + +By default, a `serverTimestamp()` that has not yet been set to its final value will be returned as `null`. You can override this by passing an options object. + +Signature: + +```typescript +get(fieldPath: string | FieldPath, options?: SnapshotOptions): any; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldPath | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The path (for example 'foo' or 'foo.bar') to a specific field. | +| options | [SnapshotOptions](./firestore_.snapshotoptions.md#snapshotoptions_interface) | An options object to configure how the field is retrieved from the snapshot (for example the desired behavior for server timestamps that have not yet been set to their final value). | + +Returns: + +any + +The data at the specified field location or undefined if no such field exists in the document. + diff --git a/docs-devsite/firestore_.fieldpath.md b/docs-devsite/firestore_.fieldpath.md new file mode 100644 index 00000000000..8a9143f02a8 --- /dev/null +++ b/docs-devsite/firestore_.fieldpath.md @@ -0,0 +1,72 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FieldPath class +A `FieldPath` refers to a field in a document. The path may consist of a single field name (referring to a top-level field in the document), or a list of field names (referring to a nested field in the document). + +Create a `FieldPath` by providing field names. If more than one field name is provided, the path will point to a nested field in a document. + +Signature: + +```typescript +export declare class FieldPath +``` + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(fieldNames)](./firestore_.fieldpath.md#fieldpathconstructor) | | Creates a FieldPath from the provided field names. If more than one field name is provided, the path will point to a nested field in a document. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [isEqual(other)](./firestore_.fieldpath.md#fieldpathisequal) | | Returns true if this FieldPath is equal to the provided one. | + +## FieldPath.(constructor) + +Creates a `FieldPath` from the provided field names. If more than one field name is provided, the path will point to a nested field in a document. + +Signature: + +```typescript +constructor(...fieldNames: string[]); +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldNames | string\[\] | A list of field names. | + +## FieldPath.isEqual() + +Returns true if this `FieldPath` is equal to the provided one. + +Signature: + +```typescript +isEqual(other: FieldPath): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| other | [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The FieldPath to compare against. | + +Returns: + +boolean + +true if this `FieldPath` is equal to the provided one. + diff --git a/docs-devsite/firestore_.fieldvalue.md b/docs-devsite/firestore_.fieldvalue.md new file mode 100644 index 00000000000..62c034583d6 --- /dev/null +++ b/docs-devsite/firestore_.fieldvalue.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FieldValue class +Sentinel values that can be used when writing document fields with `set()` or `update()`. + +Signature: + +```typescript +export declare abstract class FieldValue +``` + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [isEqual(other)](./firestore_.fieldvalue.md#fieldvalueisequal) | | Compares FieldValues for equality. | + +## FieldValue.isEqual() + +Compares `FieldValue`s for equality. + +Signature: + +```typescript +abstract isEqual(other: FieldValue): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| other | [FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) | | + +Returns: + +boolean + diff --git a/docs-devsite/firestore_.firestore.md b/docs-devsite/firestore_.firestore.md new file mode 100644 index 00000000000..01267d5b2d3 --- /dev/null +++ b/docs-devsite/firestore_.firestore.md @@ -0,0 +1,68 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Firestore class +The Cloud Firestore service interface. + +Do not call this constructor directly. Instead, use [getFirestore()](./firestore_.md#getfirestore). + +Signature: + +```typescript +export declare class Firestore +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [app](./firestore_.firestore.md#firestoreapp) | | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this Firestore service instance. | +| [type](./firestore_.firestore.md#firestoretype) | | 'firestore-lite' \| 'firestore' | Whether it's a [Firestore](./firestore_.firestore.md#firestore_class) or Firestore Lite instance. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [toJSON()](./firestore_.firestore.md#firestoretojson) | | Returns a JSON-serializable representation of this Firestore instance. | + +## Firestore.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this `Firestore` service instance. + +Signature: + +```typescript +get app(): FirebaseApp; +``` + +## Firestore.type + +Whether it's a [Firestore](./firestore_.firestore.md#firestore_class) or Firestore Lite instance. + +Signature: + +```typescript +type: 'firestore-lite' | 'firestore'; +``` + +## Firestore.toJSON() + +Returns a JSON-serializable representation of this `Firestore` instance. + +Signature: + +```typescript +toJSON(): object; +``` +Returns: + +object + diff --git a/docs-devsite/firestore_.firestoredataconverter.md b/docs-devsite/firestore_.firestoredataconverter.md new file mode 100644 index 00000000000..f7d80ac4a13 --- /dev/null +++ b/docs-devsite/firestore_.firestoredataconverter.md @@ -0,0 +1,134 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FirestoreDataConverter interface +Converter used by `withConverter()` to transform user objects of type `T` into Firestore data. + +Using the converter allows you to specify generic type arguments when storing and retrieving objects from Firestore. + +Signature: + +```typescript +export declare interface FirestoreDataConverter +``` + +## Methods + +| Method | Description | +| --- | --- | +| [fromFirestore(snapshot, options)](./firestore_.firestoredataconverter.md#firestoredataconverterfromfirestore) | Called by the Firestore SDK to convert Firestore data into an object of type T. You can access your data by calling: snapshot.data(options). | +| [toFirestore(modelObject)](./firestore_.firestoredataconverter.md#firestoredataconvertertofirestore) | Called by the Firestore SDK to convert a custom model object of type T into a plain JavaScript object (suitable for writing directly to the Firestore database). To use set() with merge and mergeFields, toFirestore() must be defined with PartialWithFieldValue<T>.The WithFieldValue<T> type extends T to also allow FieldValues such as [deleteField()](./firestore_.md#deletefield) to be used as property values. | +| [toFirestore(modelObject, options)](./firestore_.firestoredataconverter.md#firestoredataconvertertofirestore) | Called by the Firestore SDK to convert a custom model object of type T into a plain JavaScript object (suitable for writing directly to the Firestore database). Used with [setDoc()](./firestore_.md#setdoc), and with merge:true or mergeFields.The PartialWithFieldValue<T> type extends Partial<T> to allow FieldValues such as [arrayUnion()](./firestore_.md#arrayunion) to be used as property values. It also supports nested Partial by allowing nested fields to be omitted. | + +## FirestoreDataConverter.fromFirestore() + +Called by the Firestore SDK to convert Firestore data into an object of type T. You can access your data by calling: `snapshot.data(options)`. + +Signature: + +```typescript +fromFirestore(snapshot: QueryDocumentSnapshot, options?: SnapshotOptions): T; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| snapshot | [QueryDocumentSnapshot](./firestore_.querydocumentsnapshot.md#querydocumentsnapshot_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> | A QueryDocumentSnapshot containing your data and metadata. | +| options | [SnapshotOptions](./firestore_.snapshotoptions.md#snapshotoptions_interface) | The SnapshotOptions from the initial call to data(). | + +Returns: + +T + +## FirestoreDataConverter.toFirestore() + +Called by the Firestore SDK to convert a custom model object of type `T` into a plain JavaScript object (suitable for writing directly to the Firestore database). To use `set()` with `merge` and `mergeFields`, `toFirestore()` must be defined with `PartialWithFieldValue`. + +The `WithFieldValue` type extends `T` to also allow FieldValues such as [deleteField()](./firestore_.md#deletefield) to be used as property values. + +Signature: + +```typescript +toFirestore(modelObject: WithFieldValue): DocumentData; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| modelObject | [WithFieldValue](./firestore_.md#withfieldvalue)<T> | | + +Returns: + +[DocumentData](./firestore_.documentdata.md#documentdata_interface) + +## FirestoreDataConverter.toFirestore() + +Called by the Firestore SDK to convert a custom model object of type `T` into a plain JavaScript object (suitable for writing directly to the Firestore database). Used with [setDoc()](./firestore_.md#setdoc), and with `merge:true` or `mergeFields`. + +The `PartialWithFieldValue` type extends `Partial` to allow FieldValues such as [arrayUnion()](./firestore_.md#arrayunion) to be used as property values. It also supports nested `Partial` by allowing nested fields to be omitted. + +Signature: + +```typescript +toFirestore(modelObject: PartialWithFieldValue, options: SetOptions): DocumentData; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| modelObject | [PartialWithFieldValue](./firestore_.md#partialwithfieldvalue)<T> | | +| options | [SetOptions](./firestore_.md#setoptions) | | + +Returns: + +[DocumentData](./firestore_.documentdata.md#documentdata_interface) + +### Example + + +```typescript +class Post { + constructor(readonly title: string, readonly author: string) {} + + toString(): string { + return this.title + ', by ' + this.author; + } +} + +const postConverter = { + toFirestore(post: WithFieldValue): DocumentData { + return {title: post.title, author: post.author}; + }, + fromFirestore( + snapshot: QueryDocumentSnapshot, + options: SnapshotOptions + ): Post { + const data = snapshot.data(options)!; + return new Post(data.title, data.author); + } +}; + +const postSnap = await firebase.firestore() + .collection('posts') + .withConverter(postConverter) + .doc().get(); +const post = postSnap.data(); +if (post !== undefined) { + post.title; // string + post.toString(); // Should be defined + post.someNonExistentProperty; // TS error +} + +``` + diff --git a/docs-devsite/firestore_.firestoreerror.md b/docs-devsite/firestore_.firestoreerror.md new file mode 100644 index 00000000000..c16cf39541e --- /dev/null +++ b/docs-devsite/firestore_.firestoreerror.md @@ -0,0 +1,58 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FirestoreError class +An error returned by a Firestore operation. + +Signature: + +```typescript +export declare class FirestoreError extends FirebaseError +``` +Extends: [FirebaseError](./util.firebaseerror.md#firebaseerror_class) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [code](./firestore_.firestoreerror.md#firestoreerrorcode) | | [FirestoreErrorCode](./firestore_.md#firestoreerrorcode) | The backend error code associated with this error. | +| [message](./firestore_.firestoreerror.md#firestoreerrormessage) | | string | A custom error description. | +| [stack](./firestore_.firestoreerror.md#firestoreerrorstack) | | string | The stack of the error. | + +## FirestoreError.code + +The backend error code associated with this error. + +Signature: + +```typescript +readonly code: FirestoreErrorCode; +``` + +## FirestoreError.message + +A custom error description. + +Signature: + +```typescript +readonly message: string; +``` + +## FirestoreError.stack + +The stack of the error. + +Signature: + +```typescript +readonly stack?: string; +``` diff --git a/docs-devsite/firestore_.firestoresettings.md b/docs-devsite/firestore_.firestoresettings.md new file mode 100644 index 00000000000..96fe454cb77 --- /dev/null +++ b/docs-devsite/firestore_.firestoresettings.md @@ -0,0 +1,96 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FirestoreSettings interface +Specifies custom configurations for your Cloud Firestore instance. You must set these before invoking any other methods. + +Signature: + +```typescript +export declare interface FirestoreSettings +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [cacheSizeBytes](./firestore_.firestoresettings.md#firestoresettingscachesizebytes) | number | An approximate cache size threshold for the on-disk data. If the cache grows beyond this size, Firestore will start removing data that hasn't been recently used. The size is not a guarantee that the cache will stay below that size, only that if the cache exceeds the given size, cleanup will be attempted.The default value is 40 MB. The threshold must be set to at least 1 MB, and can be set to CACHE_SIZE_UNLIMITED to disable garbage collection. | +| [experimentalAutoDetectLongPolling](./firestore_.firestoresettings.md#firestoresettingsexperimentalautodetectlongpolling) | boolean | Configures the SDK's underlying transport (WebChannel) to automatically detect if long-polling should be used. This is very similar to experimentalForceLongPolling, but only uses long-polling if required.This setting will likely be enabled by default in future releases and cannot be combined with experimentalForceLongPolling. | +| [experimentalForceLongPolling](./firestore_.firestoresettings.md#firestoresettingsexperimentalforcelongpolling) | boolean | Forces the SDK’s underlying network transport (WebChannel) to use long-polling. Each response from the backend will be closed immediately after the backend sends data (by default responses are kept open in case the backend has more data to send). This avoids incompatibility issues with certain proxies, antivirus software, etc. that incorrectly buffer traffic indefinitely. Use of this option will cause some performance degradation though.This setting cannot be used with experimentalAutoDetectLongPolling and may be removed in a future release. If you find yourself using it to work around a specific network reliability issue, please tell us about it in https://github.com/firebase/firebase-js-sdk/issues/1674. | +| [host](./firestore_.firestoresettings.md#firestoresettingshost) | string | The hostname to connect to. | +| [ignoreUndefinedProperties](./firestore_.firestoresettings.md#firestoresettingsignoreundefinedproperties) | boolean | Whether to skip nested properties that are set to undefined during object serialization. If set to true, these properties are skipped and not written to Firestore. If set to false or omitted, the SDK throws an exception when it encounters properties of type undefined. | +| [ssl](./firestore_.firestoresettings.md#firestoresettingsssl) | boolean | Whether to use SSL when connecting. | + +## FirestoreSettings.cacheSizeBytes + +An approximate cache size threshold for the on-disk data. If the cache grows beyond this size, Firestore will start removing data that hasn't been recently used. The size is not a guarantee that the cache will stay below that size, only that if the cache exceeds the given size, cleanup will be attempted. + +The default value is 40 MB. The threshold must be set to at least 1 MB, and can be set to `CACHE_SIZE_UNLIMITED` to disable garbage collection. + +Signature: + +```typescript +cacheSizeBytes?: number; +``` + +## FirestoreSettings.experimentalAutoDetectLongPolling + +Configures the SDK's underlying transport (WebChannel) to automatically detect if long-polling should be used. This is very similar to `experimentalForceLongPolling`, but only uses long-polling if required. + +This setting will likely be enabled by default in future releases and cannot be combined with `experimentalForceLongPolling`. + +Signature: + +```typescript +experimentalAutoDetectLongPolling?: boolean; +``` + +## FirestoreSettings.experimentalForceLongPolling + +Forces the SDK’s underlying network transport (WebChannel) to use long-polling. Each response from the backend will be closed immediately after the backend sends data (by default responses are kept open in case the backend has more data to send). This avoids incompatibility issues with certain proxies, antivirus software, etc. that incorrectly buffer traffic indefinitely. Use of this option will cause some performance degradation though. + +This setting cannot be used with `experimentalAutoDetectLongPolling` and may be removed in a future release. If you find yourself using it to work around a specific network reliability issue, please tell us about it in https://github.com/firebase/firebase-js-sdk/issues/1674. + +Signature: + +```typescript +experimentalForceLongPolling?: boolean; +``` + +## FirestoreSettings.host + +The hostname to connect to. + +Signature: + +```typescript +host?: string; +``` + +## FirestoreSettings.ignoreUndefinedProperties + +Whether to skip nested properties that are set to `undefined` during object serialization. If set to `true`, these properties are skipped and not written to Firestore. If set to `false` or omitted, the SDK throws an exception when it encounters properties of type `undefined`. + +Signature: + +```typescript +ignoreUndefinedProperties?: boolean; +``` + +## FirestoreSettings.ssl + +Whether to use SSL when connecting. + +Signature: + +```typescript +ssl?: boolean; +``` diff --git a/docs-devsite/firestore_.geopoint.md b/docs-devsite/firestore_.geopoint.md new file mode 100644 index 00000000000..d2fd1bd7392 --- /dev/null +++ b/docs-devsite/firestore_.geopoint.md @@ -0,0 +1,117 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# GeoPoint class +An immutable object representing a geographic location in Firestore. The location is represented as latitude/longitude pair. + +Latitude values are in the range of \[-90, 90\]. Longitude values are in the range of \[-180, 180\]. + +Signature: + +```typescript +export declare class GeoPoint +``` + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(latitude, longitude)](./firestore_.geopoint.md#geopointconstructor) | | Creates a new immutable GeoPoint object with the provided latitude and longitude values. | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [latitude](./firestore_.geopoint.md#geopointlatitude) | | number | The latitude of this GeoPoint instance. | +| [longitude](./firestore_.geopoint.md#geopointlongitude) | | number | The longitude of this GeoPoint instance. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [isEqual(other)](./firestore_.geopoint.md#geopointisequal) | | Returns true if this GeoPoint is equal to the provided one. | +| [toJSON()](./firestore_.geopoint.md#geopointtojson) | | Returns a JSON-serializable representation of this GeoPoint. | + +## GeoPoint.(constructor) + +Creates a new immutable `GeoPoint` object with the provided latitude and longitude values. + +Signature: + +```typescript +constructor(latitude: number, longitude: number); +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| latitude | number | The latitude as number between -90 and 90. | +| longitude | number | The longitude as number between -180 and 180. | + +## GeoPoint.latitude + +The latitude of this `GeoPoint` instance. + +Signature: + +```typescript +get latitude(): number; +``` + +## GeoPoint.longitude + +The longitude of this `GeoPoint` instance. + +Signature: + +```typescript +get longitude(): number; +``` + +## GeoPoint.isEqual() + +Returns true if this `GeoPoint` is equal to the provided one. + +Signature: + +```typescript +isEqual(other: GeoPoint): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| other | [GeoPoint](./firestore_.geopoint.md#geopoint_class) | The GeoPoint to compare against. | + +Returns: + +boolean + +true if this `GeoPoint` is equal to the provided one. + +## GeoPoint.toJSON() + +Returns a JSON-serializable representation of this GeoPoint. + +Signature: + +```typescript +toJSON(): { + latitude: number; + longitude: number; + }; +``` +Returns: + +{ latitude: number; longitude: number; } + diff --git a/docs-devsite/firestore_.index.md b/docs-devsite/firestore_.index.md new file mode 100644 index 00000000000..3ea216d6798 --- /dev/null +++ b/docs-devsite/firestore_.index.md @@ -0,0 +1,55 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Index interface +> 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. +> + +The SDK definition of a Firestore index. + +Signature: + +```typescript +export declare interface Index +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [collectionGroup](./firestore_.index.md#indexcollectiongroup) | string | (BETA) The ID of the collection to index. | +| [fields](./firestore_.index.md#indexfields) | [IndexField](./firestore_.indexfield.md#indexfield_interface)\[\] | (BETA) A list of fields to index. | + +## Index.collectionGroup + +> 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. +> + +The ID of the collection to index. + +Signature: + +```typescript +readonly collectionGroup: string; +``` + +## Index.fields + +> 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. +> + +A list of fields to index. + +Signature: + +```typescript +readonly fields?: IndexField[]; +``` diff --git a/docs-devsite/firestore_.indexconfiguration.md b/docs-devsite/firestore_.indexconfiguration.md new file mode 100644 index 00000000000..8a0592e7ed6 --- /dev/null +++ b/docs-devsite/firestore_.indexconfiguration.md @@ -0,0 +1,43 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# IndexConfiguration interface +> 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. +> + +A list of Firestore indexes to speed up local query execution. + +See [JSON Format](https://firebase.google.com/docs/reference/firestore/indexes/#json_format) for a description of the format of the index definition. + +Signature: + +```typescript +export declare interface IndexConfiguration +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [indexes](./firestore_.indexconfiguration.md#indexconfigurationindexes) | [Index](./firestore_.index.md#index_interface)\[\] | (BETA) A list of all Firestore indexes. | + +## IndexConfiguration.indexes + +> 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. +> + +A list of all Firestore indexes. + +Signature: + +```typescript +readonly indexes?: Index[]; +``` diff --git a/docs-devsite/firestore_.indexfield.md b/docs-devsite/firestore_.indexfield.md new file mode 100644 index 00000000000..278e2f63ce8 --- /dev/null +++ b/docs-devsite/firestore_.indexfield.md @@ -0,0 +1,73 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# IndexField interface +> 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. +> + +A single field element in an index configuration. + +Signature: + +```typescript +export declare interface IndexField +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [arrayConfig](./firestore_.indexfield.md#indexfieldarrayconfig) | 'CONTAINS' | (BETA) What type of array index to create. Set to CONTAINS for array-contains and array-contains-any indexes.Only one of arrayConfig or order should be set; | +| [fieldPath](./firestore_.indexfield.md#indexfieldfieldpath) | string | (BETA) The field path to index. | +| [order](./firestore_.indexfield.md#indexfieldorder) | 'ASCENDING' \| 'DESCENDING' | (BETA) What type of array index to create. Set to ASCENDING or 'DESCENDING for ==, !=, <=, <=, in and not-in\` filters.Only one of arrayConfig or order should be set. | + +## IndexField.arrayConfig + +> 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. +> + +What type of array index to create. Set to `CONTAINS` for `array-contains` and `array-contains-any` indexes. + +Only one of `arrayConfig` or `order` should be set; + +Signature: + +```typescript +readonly arrayConfig?: 'CONTAINS'; +``` + +## IndexField.fieldPath + +> 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. +> + +The field path to index. + +Signature: + +```typescript +readonly fieldPath: string; +``` + +## IndexField.order + +> 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. +> + +What type of array index to create. Set to `ASCENDING` or 'DESCENDING` for `==`, `!=`, `<=`, `<=`, `in` and `not-in\` filters. + +Only one of `arrayConfig` or `order` should be set. + +Signature: + +```typescript +readonly order?: 'ASCENDING' | 'DESCENDING'; +``` diff --git a/docs-devsite/firestore_.loadbundletask.md b/docs-devsite/firestore_.loadbundletask.md new file mode 100644 index 00000000000..8b446d5d6e1 --- /dev/null +++ b/docs-devsite/firestore_.loadbundletask.md @@ -0,0 +1,94 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# LoadBundleTask class +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`. + +Signature: + +```typescript +export declare class LoadBundleTask implements PromiseLike +``` +Implements: PromiseLike<[LoadBundleTaskProgress](./firestore_.loadbundletaskprogress.md#loadbundletaskprogress_interface)> + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [catch(onRejected)](./firestore_.loadbundletask.md#loadbundletaskcatch) | | Implements the Promise<LoadBundleTaskProgress>.catch interface. | +| [onProgress(next, error, complete)](./firestore_.loadbundletask.md#loadbundletaskonprogress) | | Registers functions to listen to bundle loading progress events. | +| [then(onFulfilled, onRejected)](./firestore_.loadbundletask.md#loadbundletaskthen) | | Implements the Promise<LoadBundleTaskProgress>.then interface. | + +## LoadBundleTask.catch() + +Implements the `Promise.catch` interface. + +Signature: + +```typescript +catch(onRejected: (a: Error) => R | PromiseLike): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| onRejected | (a: Error) => R \| PromiseLike<R> | Called when an error occurs during bundle loading. | + +Returns: + +Promise<R \| [LoadBundleTaskProgress](./firestore_.loadbundletaskprogress.md#loadbundletaskprogress_interface)> + +## LoadBundleTask.onProgress() + +Registers functions to listen to bundle loading progress events. + +Signature: + +```typescript +onProgress(next?: (progress: LoadBundleTaskProgress) => unknown, error?: (err: Error) => unknown, complete?: () => void): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| next | (progress: [LoadBundleTaskProgress](./firestore_.loadbundletaskprogress.md#loadbundletaskprogress_interface)) => unknown | Called when there is a progress update from bundle loading. Typically next calls occur each time a Firestore document is loaded from the bundle. | +| error | (err: Error) => unknown | Called when an error occurs during bundle loading. The task aborts after reporting the error, and there should be no more updates after this. | +| complete | () => void | Called when the loading task is complete. | + +Returns: + +void + +## LoadBundleTask.then() + +Implements the `Promise.then` interface. + +Signature: + +```typescript +then(onFulfilled?: (a: LoadBundleTaskProgress) => T | PromiseLike, onRejected?: (a: Error) => R | PromiseLike): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| onFulfilled | (a: [LoadBundleTaskProgress](./firestore_.loadbundletaskprogress.md#loadbundletaskprogress_interface)) => T \| PromiseLike<T> | Called on the completion of the loading task with a final LoadBundleTaskProgress update. The update will always have its taskState set to "Success". | +| onRejected | (a: Error) => R \| PromiseLike<R> | Called when an error occurs during bundle loading. | + +Returns: + +Promise<T \| R> + diff --git a/docs-devsite/firestore_.loadbundletaskprogress.md b/docs-devsite/firestore_.loadbundletaskprogress.md new file mode 100644 index 00000000000..98124754928 --- /dev/null +++ b/docs-devsite/firestore_.loadbundletaskprogress.md @@ -0,0 +1,79 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# LoadBundleTaskProgress interface +Represents a progress update or a final state from loading bundles. + +Signature: + +```typescript +export declare interface LoadBundleTaskProgress +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [bytesLoaded](./firestore_.loadbundletaskprogress.md#loadbundletaskprogressbytesloaded) | number | How many bytes have been loaded. | +| [documentsLoaded](./firestore_.loadbundletaskprogress.md#loadbundletaskprogressdocumentsloaded) | number | How many documents have been loaded. | +| [taskState](./firestore_.loadbundletaskprogress.md#loadbundletaskprogresstaskstate) | [TaskState](./firestore_.md#taskstate) | Current task state. | +| [totalBytes](./firestore_.loadbundletaskprogress.md#loadbundletaskprogresstotalbytes) | number | How many bytes are in the bundle being loaded. | +| [totalDocuments](./firestore_.loadbundletaskprogress.md#loadbundletaskprogresstotaldocuments) | number | How many documents are in the bundle being loaded. | + +## LoadBundleTaskProgress.bytesLoaded + +How many bytes have been loaded. + +Signature: + +```typescript +bytesLoaded: number; +``` + +## LoadBundleTaskProgress.documentsLoaded + +How many documents have been loaded. + +Signature: + +```typescript +documentsLoaded: number; +``` + +## LoadBundleTaskProgress.taskState + +Current task state. + +Signature: + +```typescript +taskState: TaskState; +``` + +## LoadBundleTaskProgress.totalBytes + +How many bytes are in the bundle being loaded. + +Signature: + +```typescript +totalBytes: number; +``` + +## LoadBundleTaskProgress.totalDocuments + +How many documents are in the bundle being loaded. + +Signature: + +```typescript +totalDocuments: number; +``` diff --git a/docs-devsite/firestore_.md b/docs-devsite/firestore_.md new file mode 100644 index 00000000000..4a5c2dd49b2 --- /dev/null +++ b/docs-devsite/firestore_.md @@ -0,0 +1,2134 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# @firebase/firestore + +## Functions + +| Function | Description | +| --- | --- | +| 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. | +| [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. | +| [collection(firestore, path, pathSegments)](./firestore_.md#collection) | Gets a CollectionReference instance that refers to the collection at the specified absolute path. | +| [collectionGroup(firestore, collectionId)](./firestore_.md#collectiongroup) | Creates and returns a new Query instance that includes all documents in the database that are contained in a collection or subcollection with the given collectionId. | +| [connectFirestoreEmulator(firestore, host, port, options)](./firestore_.md#connectfirestoreemulator) | Modify this instance to communicate with the Cloud Firestore emulator.Note: This must be called before this instance has been used to do any operations. | +| [disableNetwork(firestore)](./firestore_.md#disablenetwork) | Disables network usage for this instance. It can be re-enabled via [enableNetwork()](./firestore_.md#enablenetwork). While the network is disabled, any snapshot listeners, getDoc() or getDocs() calls will return results from cache, and any write operations will be queued until the network is restored. | +| [doc(firestore, path, pathSegments)](./firestore_.md#doc) | Gets a DocumentReference instance that refers to the document at the specified absolute path. | +| [enableIndexedDbPersistence(firestore, persistenceSettings)](./firestore_.md#enableindexeddbpersistence) | Attempts to enable persistent storage, if possible.Must be called before any other functions (other than [initializeFirestore()](./firestore_.md#initializefirestore), [getFirestore()](./firestore_.md#getfirestore) or [clearIndexedDbPersistence()](./firestore_.md#clearindexeddbpersistence).If this fails, enableIndexedDbPersistence() will reject the promise it returns. Note that even after this failure, the [Firestore](./firestore_.firestore.md#firestore_class) instance will remain usable, however offline persistence will be disabled.There are several reasons why this can fail, which can be identified by the code on the error.\* failed-precondition: The app is already open in another browser tab. \* unimplemented: The browser is incompatible with the offline persistence implementation. | +| [enableMultiTabIndexedDbPersistence(firestore)](./firestore_.md#enablemultitabindexeddbpersistence) | Attempts to enable multi-tab persistent storage, if possible. If enabled across all tabs, all operations share access to local persistence, including shared execution of queries and latency-compensated local document updates across all connected instances.If this fails, enableMultiTabIndexedDbPersistence() will reject the promise it returns. Note that even after this failure, the [Firestore](./firestore_.firestore.md#firestore_class) instance will remain usable, however offline persistence will be disabled.There are several reasons why this can fail, which can be identified by the code on the error.\* failed-precondition: The app is already open in another browser tab and multi-tab is not enabled. \* unimplemented: The browser is incompatible with the offline persistence implementation. | +| [enableNetwork(firestore)](./firestore_.md#enablenetwork) | Re-enables use of the network for this [Firestore](./firestore_.firestore.md#firestore_class) instance after a prior call to [disableNetwork()](./firestore_.md#disablenetwork). | +| [loadBundle(firestore, bundleData)](./firestore_.md#loadbundle) | Loads a Firestore bundle into the local cache. | +| [namedQuery(firestore, name)](./firestore_.md#namedquery) | Reads a Firestore [Query](./firestore_.query.md#query_class) 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](./firestore_.query.md#query_class) by name. | +| [onSnapshotsInSync(firestore, observer)](./firestore_.md#onsnapshotsinsync) | Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners.NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use SnapshotMetadata in the individual listeners to determine if a snapshot is from the cache or the server. | +| [onSnapshotsInSync(firestore, onSync)](./firestore_.md#onsnapshotsinsync) | Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners.NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use SnapshotMetadata in the individual listeners to determine if a snapshot is from the cache or the server. | +| [runTransaction(firestore, updateFunction, options)](./firestore_.md#runtransaction) | Executes the given updateFunction and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, Cloud Firestore retries the updateFunction. If it fails to commit after 5 attempts, the transaction fails.The maximum number of writes allowed in a single transaction is 500. | +| [setIndexConfiguration(firestore, configuration)](./firestore_.md#setindexconfiguration) | (BETA) Configures indexing for local query execution. Any previous index configuration is overridden. The Promise resolves once the index configuration has been persisted.The index entries themselves are created asynchronously. You can continue to use queries that require indexing even if the indices are not yet available. Query execution will automatically start using the index once the index entries have been written.Indexes are only supported with IndexedDb persistence. Invoke either enableIndexedDbPersistence() or enableMultiTabIndexedDbPersistence() before setting an index configuration. If IndexedDb is not enabled, any index configuration is ignored. | +| [setIndexConfiguration(firestore, json)](./firestore_.md#setindexconfiguration) | (BETA) Configures indexing for local query execution. Any previous index configuration is overridden. The Promise resolves once the index configuration has been persisted.The index entries themselves are created asynchronously. You can continue to use queries that require indexing even if the indices are not yet available. Query execution will automatically start using the index once the index entries have been written.Indexes are only supported with IndexedDb persistence. Invoke either enableIndexedDbPersistence() or enableMultiTabIndexedDbPersistence() before setting an index configuration. If IndexedDb is not enabled, any index configuration is ignored.The method accepts the JSON format exported by the Firebase CLI (firebase firestore:indexes). If the JSON format is invalid, this method throws an error. | +| [terminate(firestore)](./firestore_.md#terminate) | Terminates the provided [Firestore](./firestore_.firestore.md#firestore_class) instance.After calling terminate() only the clearIndexedDbPersistence() function may be used. Any other function will throw a FirestoreError.To restart after termination, create a new instance of FirebaseFirestore with [getFirestore()](./firestore_.md#getfirestore).Termination does not cancel any pending writes, and any promises that are awaiting a response from the server will not be resolved. If you have persistence enabled, the next time you start this instance, it will resume sending these writes to the server.Note: Under normal circumstances, calling terminate() is not required. This function is useful only when you want to force this instance to release all of its resources or in combination with clearIndexedDbPersistence() to ensure that all local state is destroyed between test runs. | +| [waitForPendingWrites(firestore)](./firestore_.md#waitforpendingwrites) | Waits until all currently pending writes for the active user have been acknowledged by the backend.The returned promise resolves immediately if there are no outstanding writes. Otherwise, the promise waits for all previously issued writes (including those written in a previous app session), but it does not wait for writes that were added after the function is called. If you want to wait for additional writes, call waitForPendingWrites() again.Any outstanding waitForPendingWrites() promises are rejected during user changes. | +| [writeBatch(firestore)](./firestore_.md#writebatch) | Creates a write batch, used for performing multiple writes as a single atomic operation. The maximum number of writes allowed in a single [WriteBatch](./firestore_.writebatch.md#writebatch_class) is 500.Unlike transactions, write batches are persisted offline and therefore are preferable when you don't need to condition your writes on read data. | +| function() | +| [deleteField()](./firestore_.md#deletefield) | Returns a sentinel for use with [updateDoc()](./firestore_lite.md#updatedoc) or [setDoc()](./firestore_lite.md#setdoc) with {merge: true} to mark a field for deletion. | +| [documentId()](./firestore_.md#documentid) | Returns a special sentinel FieldPath to refer to the ID of a document. It can be used in queries to sort or filter by the document ID. | +| [getFirestore()](./firestore_.md#getfirestore) | Returns the existing default [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. | +| [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(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. | +| function(fieldPath...) | +| [orderBy(fieldPath, directionStr)](./firestore_.md#orderby) | Creates a [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class) that sorts the query result by the specified field, optionally in descending order instead of ascending.Note: Documents that do not contain the specified field will not be present in the query result. | +| [where(fieldPath, opStr, value)](./firestore_.md#where) | Creates a [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) that enforces that documents must contain the specified field and that the value should satisfy the relation constraint provided. | +| function(fieldValues...) | +| [endAt(fieldValues)](./firestore_.md#endat) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | +| [endBefore(fieldValues)](./firestore_.md#endbefore) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | +| [startAfter(fieldValues)](./firestore_.md#startafter) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | +| [startAt(fieldValues)](./firestore_.md#startat) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | +| function(left...) | +| [aggregateQuerySnapshotEqual(left, right)](./firestore_.md#aggregatequerysnapshotequal) | Compares two AggregateQuerySnapshot instances for equality.Two AggregateQuerySnapshot instances are considered "equal" if they have underlying queries that compare equal, and the same data. | +| [queryEqual(left, right)](./firestore_.md#queryequal) | Returns true if the provided queries point to the same collection and apply the same constraints. | +| [refEqual(left, right)](./firestore_.md#refequal) | Returns true if the provided references are equal. | +| [snapshotEqual(left, right)](./firestore_.md#snapshotequal) | Returns true if the provided snapshots are equal. | +| function(limit...) | +| [limit(limit)](./firestore_.md#limit) | Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the first matching documents. | +| [limitToLast(limit)](./firestore_.md#limittolast) | Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the last matching documents.You must specify at least one orderBy clause for limitToLast queries, otherwise an exception will be thrown during execution. | +| function(logLevel...) | +| [setLogLevel(logLevel)](./firestore_.md#setloglevel) | Sets the verbosity of Cloud Firestore logs (debug, error, or silent). | +| function(n...) | +| [increment(n)](./firestore_.md#increment) | 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 increment the field's current value by the given value.If either the operand or the current field value uses floating point precision, all arithmetic follows IEEE 754 semantics. If both values are integers, values outside of JavaScript's safe number range (Number.MIN_SAFE_INTEGER to Number.MAX_SAFE_INTEGER) are also subject to precision loss. Furthermore, once processed by the Firestore backend, all integer operations are capped between -2^63 and 2^63-1.If the current field value is not of type number, or if the field does not yet exist, the transformation sets the field to the given value. | +| function(query...) | +| [getCountFromServer(query)](./firestore_.md#getcountfromserver) | Calculates the number of documents in the result set of the given query, without actually downloading the documents.Using this function to count the documents is efficient because only the final count, not the documents' data, is downloaded. This function can even count the documents if the result set would be prohibitively large to download entirely (e.g. thousands of documents).The result received from the server is presented, unaltered, without considering any local state. That is, documents in the local cache are not taken into consideration, neither are local modifications not yet synchronized with the server. Previously-downloaded results, if any, are not used: every request using this source necessarily involves a round trip to the server. | +| [getDocs(query)](./firestore_.md#getdocs) | Executes the query and returns the results as a QuerySnapshot.Note: getDocs() attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. To specify this behavior, invoke [getDocsFromCache()](./firestore_.md#getdocsfromcache) or [getDocsFromServer()](./firestore_.md#getdocsfromserver). | +| [getDocsFromCache(query)](./firestore_.md#getdocsfromcache) | Executes the query and returns the results as a QuerySnapshot from cache. Returns an empty result set if no documents matching the query are currently cached. | +| [getDocsFromServer(query)](./firestore_.md#getdocsfromserver) | Executes the query and returns the results as a QuerySnapshot from the server. Returns an error if the network is not available. | +| [onSnapshot(query, observer)](./firestore_.md#onsnapshot) | Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | +| [onSnapshot(query, options, observer)](./firestore_.md#onsnapshot) | Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | +| [onSnapshot(query, onNext, onError, onCompletion)](./firestore_.md#onsnapshot) | Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | +| [onSnapshot(query, options, onNext, onError, onCompletion)](./firestore_.md#onsnapshot) | Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | +| [query(query, queryConstraints)](./firestore_.md#query) | Creates a new immutable instance of [Query](./firestore_.query.md#query_class) that is extended to also include additional query constraints. | +| function(reference...) | +| [addDoc(reference, data)](./firestore_.md#adddoc) | Add a new document to specified CollectionReference with the given data, assigning it a document ID automatically. | +| [collection(reference, path, pathSegments)](./firestore_.md#collection) | Gets a CollectionReference instance that refers to a subcollection of reference at the the specified relative path. | +| [collection(reference, path, pathSegments)](./firestore_.md#collection) | Gets a CollectionReference instance that refers to a subcollection of reference at the the specified relative path. | +| [deleteDoc(reference)](./firestore_.md#deletedoc) | Deletes the document referred to by the specified DocumentReference. | +| [doc(reference, path, pathSegments)](./firestore_.md#doc) | Gets a DocumentReference instance that refers to a document within reference at the specified relative path. If no path is specified, an automatically-generated unique ID will be used for the returned DocumentReference. | +| [doc(reference, path, pathSegments)](./firestore_.md#doc) | Gets a DocumentReference instance that refers to a document within reference at the specified relative path. | +| [getDoc(reference)](./firestore_.md#getdoc) | Reads the document referred to by this DocumentReference.Note: getDoc() attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. To specify this behavior, invoke [getDocFromCache()](./firestore_.md#getdocfromcache) or [getDocFromServer()](./firestore_.md#getdocfromserver). | +| [getDocFromCache(reference)](./firestore_.md#getdocfromcache) | Reads the document referred to by this DocumentReference from cache. Returns an error if the document is not currently cached. | +| [getDocFromServer(reference)](./firestore_.md#getdocfromserver) | Reads the document referred to by this DocumentReference from the server. Returns an error if the network is not available. | +| [onSnapshot(reference, observer)](./firestore_.md#onsnapshot) | Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | +| [onSnapshot(reference, options, observer)](./firestore_.md#onsnapshot) | Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | +| [onSnapshot(reference, onNext, onError, onCompletion)](./firestore_.md#onsnapshot) | Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | +| [onSnapshot(reference, options, onNext, onError, onCompletion)](./firestore_.md#onsnapshot) | Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | +| [setDoc(reference, data)](./firestore_.md#setdoc) | Writes to the document referred to by this DocumentReference. If the document does not yet exist, it will be created. | +| [setDoc(reference, data, options)](./firestore_.md#setdoc) | Writes to the document referred to by the specified DocumentReference. If the document does not yet exist, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document. | +| [updateDoc(reference, data)](./firestore_.md#updatedoc) | Updates fields in the document referred to by the specified DocumentReference. The update will fail if applied to a document that does not exist. | +| [updateDoc(reference, field, value, moreFieldsAndValues)](./firestore_.md#updatedoc) | Updates fields in the document referred to by the specified DocumentReference The update will fail if applied to a document that does not exist.Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects. | +| function(snapshot...) | +| [endAt(snapshot)](./firestore_.md#endat) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided document (inclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | +| [endBefore(snapshot)](./firestore_.md#endbefore) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | +| [startAfter(snapshot)](./firestore_.md#startafter) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | +| [startAt(snapshot)](./firestore_.md#startat) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of this query. | + +## Classes + +| Class | Description | +| --- | --- | +| [AggregateField](./firestore_.aggregatefield.md#aggregatefield_class) | Represents an aggregation that can be performed by Firestore. | +| [AggregateQuerySnapshot](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshot_class) | The results of executing an aggregation query. | +| [Bytes](./firestore_.bytes.md#bytes_class) | An immutable object representing an array of bytes. | +| [CollectionReference](./firestore_.collectionreference.md#collectionreference_class) | A CollectionReference object can be used for adding documents, getting document references, and querying for documents (using [query()](./firestore_.md#query)). | +| [DocumentReference](./firestore_.documentreference.md#documentreference_class) | A DocumentReference refers to a document location in a Firestore database and can be used to write, read, or listen to the location. The document at the referenced location may or may not exist. | +| [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class) | A DocumentSnapshot contains data read from a document in your Firestore database. The data can be extracted with .data() or .get(<field>) to get a specific field.For a DocumentSnapshot that points to a non-existing document, any data access will return 'undefined'. You can use the exists() method to explicitly verify a document's existence. | +| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | A FieldPath refers to a field in a document. The path may consist of a single field name (referring to a top-level field in the document), or a list of field names (referring to a nested field in the document).Create a FieldPath by providing field names. If more than one field name is provided, the path will point to a nested field in a document. | +| [FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) | Sentinel values that can be used when writing document fields with set() or update(). | +| [Firestore](./firestore_.firestore.md#firestore_class) | The Cloud Firestore service interface.Do not call this constructor directly. Instead, use [getFirestore()](./firestore_.md#getfirestore). | +| [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class) | An error returned by a Firestore operation. | +| [GeoPoint](./firestore_.geopoint.md#geopoint_class) | An immutable object representing a geographic location in Firestore. The location is represented as latitude/longitude pair.Latitude values are in the range of \[-90, 90\]. Longitude values are in the range of \[-180, 180\]. | +| [LoadBundleTask](./firestore_.loadbundletask.md#loadbundletask_class) | 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>. | +| [Query](./firestore_.query.md#query_class) | A Query refers to a query which you can read or listen to. You can also construct refined Query objects by adding filters and ordering. | +| [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) | A QueryConstraint is used to narrow the set of documents returned by a Firestore query. QueryConstraints are created by invoking [where()](./firestore_.md#where), [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit), [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryConstraint. | +| [QueryDocumentSnapshot](./firestore_.querydocumentsnapshot.md#querydocumentsnapshot_class) | A QueryDocumentSnapshot contains data read from a document in your Firestore database as part of a query. The document is guaranteed to exist and its data can be extracted with .data() or .get(<field>) to get a specific field.A QueryDocumentSnapshot offers the same API surface as a DocumentSnapshot. Since query results contain only existing documents, the exists property will always be true and data() will never return 'undefined'. | +| [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) | A QueryEndAtConstraint is used to exclude documents from the end of a result set returned by a Firestore query. QueryEndAtConstraints are created by invoking [endAt()](./firestore_.md#endat) or [endBefore()](./firestore_.md#endbefore) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryEndAtConstraint. | +| [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) | A QueryFieldFilterConstraint is used to narrow the set of documents returned by a Firestore query by filtering on one or more document fields. QueryFieldFilterConstraints are created by invoking [where()](./firestore_.md#where) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryFieldFilterConstraint. | +| [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) | A QueryLimitConstraint is used to limit the number of documents returned by a Firestore query. QueryLimitConstraints are created by invoking [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryLimitConstraint. | +| [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class) | A QueryOrderByConstraint is used to sort the set of documents returned by a Firestore query. QueryOrderByConstraints are created by invoking [orderBy()](./firestore_.md#orderby) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryOrderByConstraint.Note: Documents that do not contain the orderBy field will not be present in the query result. | +| [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class) | A QuerySnapshot contains zero or more DocumentSnapshot objects representing the results of a query. The documents can be accessed as an array via the docs property or enumerated using the forEach method. The number of documents can be determined via the empty and size properties. | +| [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) | A QueryStartAtConstraint is used to exclude documents from the start of a result set returned by a Firestore query. QueryStartAtConstraints are created by invoking [startAt()](./firestore_.md#startat) or [startAfter()](./firestore_.md#startafter) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryStartAtConstraint. | +| [SnapshotMetadata](./firestore_.snapshotmetadata.md#snapshotmetadata_class) | Metadata about a snapshot, describing the state of the snapshot. | +| [Timestamp](./firestore_.timestamp.md#timestamp_class) | A Timestamp represents a point in time independent of any time zone or calendar, represented as seconds and fractions of seconds at nanosecond resolution in UTC Epoch time.It is encoded using the Proleptic Gregorian Calendar which extends the Gregorian calendar backwards to year one. It is encoded assuming all minutes are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.For examples and further specifications, refer to the [Timestamp definition](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto). | +| [Transaction](./firestore_.transaction.md#transaction_class) | A reference to a transaction.The Transaction object passed to a transaction's updateFunction provides the methods to read and write data within the transaction context. See [runTransaction()](./firestore_.md#runtransaction). | +| [WriteBatch](./firestore_.writebatch.md#writebatch_class) | A write batch, used to perform multiple writes as a single atomic unit.A WriteBatch object can be acquired by calling [writeBatch()](./firestore_.md#writebatch). It provides methods for adding writes to the write batch. None of the writes will be committed (or visible locally) until [WriteBatch.commit()](./firestore_.writebatch.md#writebatchcommit) is called. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [AggregateSpec](./firestore_.aggregatespec.md#aggregatespec_interface) | A type whose property values are all AggregateField objects. | +| [DocumentChange](./firestore_.documentchange.md#documentchange_interface) | A DocumentChange represents a change to the documents matching a query. It contains the document affected and the type of change that occurred. | +| [DocumentData](./firestore_.documentdata.md#documentdata_interface) | Document data (for use with [setDoc()](./firestore_lite.md#setdoc)) consists of fields mapped to values. | +| [FirestoreDataConverter](./firestore_.firestoredataconverter.md#firestoredataconverter_interface) | Converter used by withConverter() to transform user objects of type T into Firestore data.Using the converter allows you to specify generic type arguments when storing and retrieving objects from Firestore. | +| [FirestoreSettings](./firestore_.firestoresettings.md#firestoresettings_interface) | Specifies custom configurations for your Cloud Firestore instance. You must set these before invoking any other methods. | +| [Index](./firestore_.index.md#index_interface) | (BETA) The SDK definition of a Firestore index. | +| [IndexConfiguration](./firestore_.indexconfiguration.md#indexconfiguration_interface) | (BETA) A list of Firestore indexes to speed up local query execution.See [JSON Format](https://firebase.google.com/docs/reference/firestore/indexes/#json_format) for a description of the format of the index definition. | +| [IndexField](./firestore_.indexfield.md#indexfield_interface) | (BETA) A single field element in an index configuration. | +| [LoadBundleTaskProgress](./firestore_.loadbundletaskprogress.md#loadbundletaskprogress_interface) | Represents a progress update or a final state from loading bundles. | +| [PersistenceSettings](./firestore_.persistencesettings.md#persistencesettings_interface) | Settings that can be passed to enableIndexedDbPersistence() to configure Firestore persistence. | +| [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | An options object that can be passed to [onSnapshot()](./firestore_.md#onsnapshot) and [QuerySnapshot.docChanges()](./firestore_.querysnapshot.md#querysnapshotdocchanges) to control which types of changes to include in the result set. | +| [SnapshotOptions](./firestore_.snapshotoptions.md#snapshotoptions_interface) | Options that configure how data is retrieved from a DocumentSnapshot (for example the desired behavior for server timestamps that have not yet been set to their final value). | +| [TransactionOptions](./firestore_.transactionoptions.md#transactionoptions_interface) | Options to customize transaction behavior. | +| [Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) | A function returned by onSnapshot() that removes the listener when invoked. | + +## Variables + +| Variable | Description | +| --- | --- | +| [CACHE\_SIZE\_UNLIMITED](./firestore_.md#cache_size_unlimited) | Constant used to indicate the LRU garbage collection should be disabled. Set this value as the cacheSizeBytes on the settings passed to the [Firestore](./firestore_.firestore.md#firestore_class) instance. | + +## Type Aliases + +| Type Alias | Description | +| --- | --- | +| [AddPrefixToKeys](./firestore_.md#addprefixtokeys) | Returns a new map where every key is prefixed with the outer key appended to a dot. | +| [AggregateFieldType](./firestore_.md#aggregatefieldtype) | The union of all AggregateField types that are supported by Firestore. | +| [AggregateSpecData](./firestore_.md#aggregatespecdata) | A type whose keys are taken from an AggregateSpec, and whose values are the result of the aggregation performed by the corresponding AggregateField from the input AggregateSpec. | +| [ChildUpdateFields](./firestore_.md#childupdatefields) | Helper for calculating the nested fields for a given type T1. This is needed to distribute union types such as undefined | {...} (happens for optional props) or {a: A} | {b: B}.In this use case, V is used to distribute the union types of T[K] on Record, since T[K] is evaluated as an expression and not distributed.See https://www.typescriptlang.org/docs/handbook/advanced-types.html\#distributive-conditional-types | +| [DocumentChangeType](./firestore_.md#documentchangetype) | The type of a DocumentChange may be 'added', 'removed', or 'modified'. | +| [FirestoreErrorCode](./firestore_.md#firestoreerrorcode) | The set of Firestore status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.mdPossible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (e.g. an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation. | +| [NestedUpdateFields](./firestore_.md#nestedupdatefields) | For each field (e.g. 'bar'), find all nested keys (e.g. {'bar.baz': T1, 'bar.qux': T2}). Intersect them together to make a single map containing all possible keys that are all marked as optional | +| [OrderByDirection](./firestore_.md#orderbydirection) | The direction of a [orderBy()](./firestore_.md#orderby) clause is specified as 'desc' or 'asc' (descending or ascending). | +| [PartialWithFieldValue](./firestore_.md#partialwithfieldvalue) | Similar to Typescript's Partial<T>, but allows nested fields to be omitted and FieldValues to be passed in as property values. | +| [Primitive](./firestore_.md#primitive) | Primitive types. | +| [QueryConstraintType](./firestore_.md#queryconstrainttype) | Describes the different query constraints available in this SDK. | +| [QueryNonFilterConstraint](./firestore_.md#querynonfilterconstraint) | QueryNonFilterConstraint is a helper union type that represents QueryConstraints which are used to narrow or order the set of documents, but that do not explicitly filter on a document field. QueryNonFilterConstraints are created by invoking [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains the QueryConstraint. | +| [SetOptions](./firestore_.md#setoptions) | An options object that configures the behavior of [setDoc()](./firestore_lite.md#setdoc), and calls. These calls can be configured to perform granular merges instead of overwriting the target documents in their entirety by providing a SetOptions with merge: true. | +| [TaskState](./firestore_.md#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. | +| [UnionToIntersection](./firestore_.md#uniontointersection) | Given a union type U = T1 | T2 | ..., returns an intersected type (T1 & T2 & ...).Uses distributive conditional types and inference from conditional types. This works because multiple candidates for the same type variable in contra-variant positions causes an intersection type to be inferred. https://www.typescriptlang.org/docs/handbook/advanced-types.html\#type-inference-in-conditional-types https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection-type | +| [UpdateData](./firestore_.md#updatedata) | Update data (for use with [updateDoc()](./firestore_.md#updatedoc)) that consists of field paths (e.g. 'foo' or 'foo.baz') mapped to values. Fields that contain dots reference nested fields within the document. FieldValues can be passed in as property values. | +| [WhereFilterOp](./firestore_.md#wherefilterop) | Filter conditions in a [where()](./firestore_.md#where) clause are specified using the strings '&lt;', '&lt;=', '==', '!=', '&gt;=', '&gt;', 'array-contains', 'in', 'array-contains-any', and 'not-in'. | +| [WithFieldValue](./firestore_.md#withfieldvalue) | Allows FieldValues to be passed in as a property value while maintaining type safety. | + +## 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. + +Signature: + +```typescript +export declare function getFirestore(app: FirebaseApp): Firestore; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance that the returned [Firestore](./firestore_.firestore.md#firestore_class) instance is associated with. | + +Returns: + +[Firestore](./firestore_.firestore.md#firestore_class) + +The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. + +## 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). + +Signature: + +```typescript +export declare function initializeFirestore(app: FirebaseApp, settings: FirestoreSettings, databaseId?: string): Firestore; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) with which the [Firestore](./firestore_.firestore.md#firestore_class) instance will be associated. | +| settings | [FirestoreSettings](./firestore_.firestoresettings.md#firestoresettings_interface) | A settings object to configure the [Firestore](./firestore_.firestore.md#firestore_class) instance. | +| databaseId | string | The name of database. | + +Returns: + +[Firestore](./firestore_.firestore.md#firestore_class) + +A newly initialized [Firestore](./firestore_.firestore.md#firestore_class) instance. + +## 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. + +Signature: + +```typescript +export declare function clearIndexedDbPersistence(firestore: Firestore): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to clear persistence for. | + +Returns: + +Promise<void> + +A `Promise` that is resolved when the persistent storage is cleared. Otherwise, the promise is rejected with an error. + +## collection() + +Gets a `CollectionReference` instance that refers to the collection at the specified absolute path. + +Signature: + +```typescript +export declare function collection(firestore: Firestore, path: string, ...pathSegments: string[]): CollectionReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | A reference to the root Firestore instance. | +| path | string | A slash-separated path to a collection. | +| pathSegments | string\[\] | Additional path segments to apply relative to the first argument. | + +Returns: + +[CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> + +The `CollectionReference` instance. + +## Exceptions + +If the final path has an even number of segments and does not point to a collection. + +## collectionGroup() + +Creates and returns a new `Query` instance that includes all documents in the database that are contained in a collection or subcollection with the given `collectionId`. + +Signature: + +```typescript +export declare function collectionGroup(firestore: Firestore, collectionId: string): Query; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | A reference to the root Firestore instance. | +| collectionId | string | Identifies the collections to query over. Every collection or subcollection with this ID as the last segment of its path will be included. Cannot contain a slash. | + +Returns: + +[Query](./firestore_.query.md#query_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> + +The created `Query`. + +## connectFirestoreEmulator() + +Modify this instance to communicate with the Cloud Firestore emulator. + +Note: This must be called before this instance has been used to do any operations. + +Signature: + +```typescript +export declare function connectFirestoreEmulator(firestore: Firestore, host: string, port: number, options?: { + mockUserToken?: EmulatorMockTokenOptions | string; +}): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The Firestore instance to configure to connect to the emulator. | +| host | string | the emulator host (ex: localhost). | +| port | number | the emulator port (ex: 9000). | +| options | { mockUserToken?: [EmulatorMockTokenOptions](./util.md#emulatormocktokenoptions) \| string; } | | + +Returns: + +void + +## disableNetwork() + +Disables network usage for this instance. It can be re-enabled via [enableNetwork()](./firestore_.md#enablenetwork). While the network is disabled, any snapshot listeners, `getDoc()` or `getDocs()` calls will return results from cache, and any write operations will be queued until the network is restored. + +Signature: + +```typescript +export declare function disableNetwork(firestore: Firestore): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | + +Returns: + +Promise<void> + +A `Promise` that is resolved once the network has been disabled. + +## doc() + +Gets a `DocumentReference` instance that refers to the document at the specified absolute path. + +Signature: + +```typescript +export declare function doc(firestore: Firestore, path: string, ...pathSegments: string[]): DocumentReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | A reference to the root Firestore instance. | +| path | string | A slash-separated path to a document. | +| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | + +Returns: + +[DocumentReference](./firestore_.documentreference.md#documentreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> + +The `DocumentReference` instance. + +## Exceptions + +If the final path has an odd number of segments and does not point to a document. + +## enableIndexedDbPersistence() + +Attempts to enable persistent storage, if possible. + +Must be called before any other functions (other than [initializeFirestore()](./firestore_.md#initializefirestore), [getFirestore()](./firestore_.md#getfirestore) or [clearIndexedDbPersistence()](./firestore_.md#clearindexeddbpersistence). + +If this fails, `enableIndexedDbPersistence()` will reject the promise it returns. Note that even after this failure, the [Firestore](./firestore_.firestore.md#firestore_class) instance will remain usable, however offline persistence will be disabled. + +There are several reasons why this can fail, which can be identified by the `code` on the error. + +\* failed-precondition: The app is already open in another browser tab. \* unimplemented: The browser is incompatible with the offline persistence implementation. + +Signature: + +```typescript +export declare function enableIndexedDbPersistence(firestore: Firestore, persistenceSettings?: PersistenceSettings): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to enable persistence for. | +| persistenceSettings | [PersistenceSettings](./firestore_.persistencesettings.md#persistencesettings_interface) | Optional settings object to configure persistence. | + +Returns: + +Promise<void> + +A `Promise` that represents successfully enabling persistent storage. + +## enableMultiTabIndexedDbPersistence() + +Attempts to enable multi-tab persistent storage, if possible. If enabled across all tabs, all operations share access to local persistence, including shared execution of queries and latency-compensated local document updates across all connected instances. + +If this fails, `enableMultiTabIndexedDbPersistence()` will reject the promise it returns. Note that even after this failure, the [Firestore](./firestore_.firestore.md#firestore_class) instance will remain usable, however offline persistence will be disabled. + +There are several reasons why this can fail, which can be identified by the `code` on the error. + +\* failed-precondition: The app is already open in another browser tab and multi-tab is not enabled. \* unimplemented: The browser is incompatible with the offline persistence implementation. + +Signature: + +```typescript +export declare function enableMultiTabIndexedDbPersistence(firestore: Firestore): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to enable persistence for. | + +Returns: + +Promise<void> + +A `Promise` that represents successfully enabling persistent storage. + +## enableNetwork() + +Re-enables use of the network for this [Firestore](./firestore_.firestore.md#firestore_class) instance after a prior call to [disableNetwork()](./firestore_.md#disablenetwork). + +Signature: + +```typescript +export declare function enableNetwork(firestore: Firestore): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | + +Returns: + +Promise<void> + +A `Promise` that is resolved once the network has been enabled. + +## loadBundle() + +Loads a Firestore bundle into the local cache. + +Signature: + +```typescript +export declare function loadBundle(firestore: Firestore, bundleData: ReadableStream | ArrayBuffer | string): LoadBundleTask; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to load bundles for. | +| bundleData | ReadableStream<Uint8Array> \| ArrayBuffer \| string | An object representing the bundle to be loaded. Valid objects are ArrayBuffer, ReadableStream<Uint8Array> or string. | + +Returns: + +[LoadBundleTask](./firestore_.loadbundletask.md#loadbundletask_class) + +A `LoadBundleTask` object, which notifies callers with progress updates, and completion or error events. It can be used as a `Promise`. + +## namedQuery() + +Reads a Firestore [Query](./firestore_.query.md#query_class) 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](./firestore_.query.md#query_class) by name. + +Signature: + +```typescript +export declare function namedQuery(firestore: Firestore, name: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to read the query from. | +| name | string | The name of the query. | + +Returns: + +Promise<[Query](./firestore_.query.md#query_class) \| null> + +A `Promise` that is resolved with the Query or `null`. + +## onSnapshotsInSync() + +Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners. + +NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use SnapshotMetadata in the individual listeners to determine if a snapshot is from the cache or the server. + +Signature: + +```typescript +export declare function onSnapshotsInSync(firestore: Firestore, observer: { + next?: (value: void) => void; + error?: (error: FirestoreError) => void; + complete?: () => void; +}): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The instance of Firestore for synchronizing snapshots. | +| observer | { next?: (value: void) => void; error?: (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void; complete?: () => void; } | A single object containing next and error callbacks. | + +Returns: + +[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) + +An unsubscribe function that can be called to cancel the snapshot listener. + +## onSnapshotsInSync() + +Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners. + +NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use `SnapshotMetadata` in the individual listeners to determine if a snapshot is from the cache or the server. + +Signature: + +```typescript +export declare function onSnapshotsInSync(firestore: Firestore, onSync: () => void): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The Firestore instance for synchronizing snapshots. | +| onSync | () => void | A callback to be called every time all snapshot listeners are in sync with each other. | + +Returns: + +[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) + +An unsubscribe function that can be called to cancel the snapshot listener. + +## runTransaction() + +Executes the given `updateFunction` and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, Cloud Firestore retries the `updateFunction`. If it fails to commit after 5 attempts, the transaction fails. + +The maximum number of writes allowed in a single transaction is 500. + +Signature: + +```typescript +export declare function runTransaction(firestore: Firestore, updateFunction: (transaction: Transaction) => Promise, options?: TransactionOptions): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | A reference to the Firestore database to run this transaction against. | +| updateFunction | (transaction: [Transaction](./firestore_.transaction.md#transaction_class)) => Promise<T> | The function to execute within the transaction context. | +| options | [TransactionOptions](./firestore_.transactionoptions.md#transactionoptions_interface) | An options object to configure maximum number of attempts to commit. | + +Returns: + +Promise<T> + +If the transaction completed successfully or was explicitly aborted (the `updateFunction` returned a failed promise), the promise returned by the `updateFunction `is returned here. Otherwise, if the transaction failed, a rejected promise with the corresponding failure error is returned. + +## setIndexConfiguration() + +> 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. +> + +Configures indexing for local query execution. Any previous index configuration is overridden. The `Promise` resolves once the index configuration has been persisted. + +The index entries themselves are created asynchronously. You can continue to use queries that require indexing even if the indices are not yet available. Query execution will automatically start using the index once the index entries have been written. + +Indexes are only supported with IndexedDb persistence. Invoke either `enableIndexedDbPersistence()` or `enableMultiTabIndexedDbPersistence()` before setting an index configuration. If IndexedDb is not enabled, any index configuration is ignored. + +Signature: + +```typescript +export declare function setIndexConfiguration(firestore: Firestore, configuration: IndexConfiguration): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to configure indexes for. | +| configuration | [IndexConfiguration](./firestore_.indexconfiguration.md#indexconfiguration_interface) | The index definition. | + +Returns: + +Promise<void> + +A `Promise` that resolves once all indices are successfully configured. + +## Exceptions + +FirestoreError if the JSON format is invalid. + +## setIndexConfiguration() + +> 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. +> + +Configures indexing for local query execution. Any previous index configuration is overridden. The `Promise` resolves once the index configuration has been persisted. + +The index entries themselves are created asynchronously. You can continue to use queries that require indexing even if the indices are not yet available. Query execution will automatically start using the index once the index entries have been written. + +Indexes are only supported with IndexedDb persistence. Invoke either `enableIndexedDbPersistence()` or `enableMultiTabIndexedDbPersistence()` before setting an index configuration. If IndexedDb is not enabled, any index configuration is ignored. + +The method accepts the JSON format exported by the Firebase CLI (`firebase firestore:indexes`). If the JSON format is invalid, this method throws an error. + +Signature: + +```typescript +export declare function setIndexConfiguration(firestore: Firestore, json: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to configure indexes for. | +| json | string | The JSON format exported by the Firebase CLI. | + +Returns: + +Promise<void> + +A `Promise` that resolves once all indices are successfully configured. + +## Exceptions + +FirestoreError if the JSON format is invalid. + +## terminate() + +Terminates the provided [Firestore](./firestore_.firestore.md#firestore_class) instance. + +After calling `terminate()` only the `clearIndexedDbPersistence()` function may be used. Any other function will throw a `FirestoreError`. + +To restart after termination, create a new instance of FirebaseFirestore with [getFirestore()](./firestore_.md#getfirestore). + +Termination does not cancel any pending writes, and any promises that are awaiting a response from the server will not be resolved. If you have persistence enabled, the next time you start this instance, it will resume sending these writes to the server. + +Note: Under normal circumstances, calling `terminate()` is not required. This function is useful only when you want to force this instance to release all of its resources or in combination with `clearIndexedDbPersistence()` to ensure that all local state is destroyed between test runs. + +Signature: + +```typescript +export declare function terminate(firestore: Firestore): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | + +Returns: + +Promise<void> + +A `Promise` that is resolved when the instance has been successfully terminated. + +## waitForPendingWrites() + +Waits until all currently pending writes for the active user have been acknowledged by the backend. + +The returned promise resolves immediately if there are no outstanding writes. Otherwise, the promise waits for all previously issued writes (including those written in a previous app session), but it does not wait for writes that were added after the function is called. If you want to wait for additional writes, call `waitForPendingWrites()` again. + +Any outstanding `waitForPendingWrites()` promises are rejected during user changes. + +Signature: + +```typescript +export declare function waitForPendingWrites(firestore: Firestore): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | + +Returns: + +Promise<void> + +A `Promise` which resolves when all currently pending writes have been acknowledged by the backend. + +## writeBatch() + +Creates a write batch, used for performing multiple writes as a single atomic operation. The maximum number of writes allowed in a single [WriteBatch](./firestore_.writebatch.md#writebatch_class) is 500. + +Unlike transactions, write batches are persisted offline and therefore are preferable when you don't need to condition your writes on read data. + +Signature: + +```typescript +export declare function writeBatch(firestore: Firestore): WriteBatch; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | + +Returns: + +[WriteBatch](./firestore_.writebatch.md#writebatch_class) + +A [WriteBatch](./firestore_.writebatch.md#writebatch_class) that can be used to atomically execute multiple writes. + +## deleteField() + +Returns a sentinel for use with [updateDoc()](./firestore_lite.md#updatedoc) or [setDoc()](./firestore_lite.md#setdoc) with `{merge: true}` to mark a field for deletion. + +Signature: + +```typescript +export declare function deleteField(): FieldValue; +``` +Returns: + +[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) + +## documentId() + +Returns a special sentinel `FieldPath` to refer to the ID of a document. It can be used in queries to sort or filter by the document ID. + +Signature: + +```typescript +export declare function documentId(): FieldPath; +``` +Returns: + +[FieldPath](./firestore_.fieldpath.md#fieldpath_class) + +## getFirestore() + +Returns the existing default [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: + +```typescript +export declare function getFirestore(): Firestore; +``` +Returns: + +[Firestore](./firestore_.firestore.md#firestore_class) + +The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. + +## 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. + +Signature: + +```typescript +export declare function serverTimestamp(): FieldValue; +``` +Returns: + +[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) + +## 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. + +Signature: + +```typescript +export declare function arrayRemove(...elements: unknown[]): FieldValue; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| elements | unknown\[\] | The elements to remove from the array. | + +Returns: + +[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) + +The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()` + +## 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. + +Signature: + +```typescript +export declare function arrayUnion(...elements: unknown[]): FieldValue; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| elements | unknown\[\] | The elements to union into the array. | + +Returns: + +[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) + +The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()`. + +## orderBy() + +Creates a [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class) that sorts the query result by the specified field, optionally in descending order instead of ascending. + +Note: Documents that do not contain the specified field will not be present in the query result. + +Signature: + +```typescript +export declare function orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDirection): QueryOrderByConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldPath | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The field to sort by. | +| directionStr | [OrderByDirection](./firestore_.md#orderbydirection) | Optional direction to sort by ('asc' or 'desc'). If not specified, order will be ascending. | + +Returns: + +[QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class) + +The created [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class). + +## where() + +Creates a [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) that enforces that documents must contain the specified field and that the value should satisfy the relation constraint provided. + +Signature: + +```typescript +export declare function where(fieldPath: string | FieldPath, opStr: WhereFilterOp, value: unknown): QueryFieldFilterConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldPath | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The path to compare | +| opStr | [WhereFilterOp](./firestore_.md#wherefilterop) | The operation string (e.g "&lt;", "&lt;=", "==", "&lt;", "&lt;=", "!="). | +| value | unknown | The value for comparison | + +Returns: + +[QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) + +The created [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class). + +## endAt() + +Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. + +Signature: + +```typescript +export declare function endAt(...fieldValues: unknown[]): QueryEndAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldValues | unknown\[\] | The field values to end this query at, in order of the query's order by. | + +Returns: + +[QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) + +A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` + +## endBefore() + +Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. + +Signature: + +```typescript +export declare function endBefore(...fieldValues: unknown[]): QueryEndAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldValues | unknown\[\] | The field values to end this query before, in order of the query's order by. | + +Returns: + +[QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) + +A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` + +## startAfter() + +Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. + +Signature: + +```typescript +export declare function startAfter(...fieldValues: unknown[]): QueryStartAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldValues | unknown\[\] | The field values to start this query after, in order of the query's order by. | + +Returns: + +[QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) + +A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()` + +## startAt() + +Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. + +Signature: + +```typescript +export declare function startAt(...fieldValues: unknown[]): QueryStartAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldValues | unknown\[\] | The field values to start this query at, in order of the query's order by. | + +Returns: + +[QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) + +A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()`. + +## aggregateQuerySnapshotEqual() + +Compares two `AggregateQuerySnapshot` instances for equality. + +Two `AggregateQuerySnapshot` instances are considered "equal" if they have underlying queries that compare equal, and the same data. + +Signature: + +```typescript +export declare function aggregateQuerySnapshotEqual(left: AggregateQuerySnapshot, right: AggregateQuerySnapshot): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| left | [AggregateQuerySnapshot](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<T> | The first AggregateQuerySnapshot to compare. | +| right | [AggregateQuerySnapshot](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<T> | The second AggregateQuerySnapshot to compare. | + +Returns: + +boolean + +`true` if the objects are "equal", as defined above, or `false` otherwise. + +## queryEqual() + +Returns true if the provided queries point to the same collection and apply the same constraints. + +Signature: + +```typescript +export declare function queryEqual(left: Query, right: Query): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| left | [Query](./firestore_.query.md#query_class)<T> | A Query to compare. | +| right | [Query](./firestore_.query.md#query_class)<T> | A Query to compare. | + +Returns: + +boolean + +true if the references point to the same location in the same Firestore database. + +## refEqual() + +Returns true if the provided references are equal. + +Signature: + +```typescript +export declare function refEqual(left: DocumentReference | CollectionReference, right: DocumentReference | CollectionReference): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| left | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> \| [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | A reference to compare. | +| right | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> \| [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | A reference to compare. | + +Returns: + +boolean + +true if the references point to the same location in the same Firestore database. + +## snapshotEqual() + +Returns true if the provided snapshots are equal. + +Signature: + +```typescript +export declare function snapshotEqual(left: DocumentSnapshot | QuerySnapshot, right: DocumentSnapshot | QuerySnapshot): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| left | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T> \| [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T> | A snapshot to compare. | +| right | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T> \| [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T> | A snapshot to compare. | + +Returns: + +boolean + +true if the snapshots are equal. + +## limit() + +Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the first matching documents. + +Signature: + +```typescript +export declare function limit(limit: number): QueryLimitConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| limit | number | The maximum number of items to return. | + +Returns: + +[QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) + +The created [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class). + +## limitToLast() + +Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the last matching documents. + +You must specify at least one `orderBy` clause for `limitToLast` queries, otherwise an exception will be thrown during execution. + +Signature: + +```typescript +export declare function limitToLast(limit: number): QueryLimitConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| limit | number | The maximum number of items to return. | + +Returns: + +[QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) + +The created [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class). + +## setLogLevel() + +Sets the verbosity of Cloud Firestore logs (debug, error, or silent). + +Signature: + +```typescript +export declare function setLogLevel(logLevel: LogLevel): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| logLevel | LogLevel | The verbosity you set for activity and error logging. Can be any of the following values:

  • debug for the most verbose logging level, primarily for debugging.
  • error to log errors only.
  • silent to turn off logging.
| + +Returns: + +void + +## increment() + +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 increment the field's current value by the given value. + +If either the operand or the current field value uses floating point precision, all arithmetic follows IEEE 754 semantics. If both values are integers, values outside of JavaScript's safe number range (`Number.MIN_SAFE_INTEGER` to `Number.MAX_SAFE_INTEGER`) are also subject to precision loss. Furthermore, once processed by the Firestore backend, all integer operations are capped between -2^63 and 2^63-1. + +If the current field value is not of type `number`, or if the field does not yet exist, the transformation sets the field to the given value. + +Signature: + +```typescript +export declare function increment(n: number): FieldValue; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| n | number | The value to increment by. | + +Returns: + +[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) + +The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()` + +## getCountFromServer() + +Calculates the number of documents in the result set of the given query, without actually downloading the documents. + +Using this function to count the documents is efficient because only the final count, not the documents' data, is downloaded. This function can even count the documents if the result set would be prohibitively large to download entirely (e.g. thousands of documents). + +The result received from the server is presented, unaltered, without considering any local state. That is, documents in the local cache are not taken into consideration, neither are local modifications not yet synchronized with the server. Previously-downloaded results, if any, are not used: every request using this source necessarily involves a round trip to the server. + +Signature: + +```typescript +export declare function getCountFromServer(query: Query): Promise; +}>>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./firestore_.query.md#query_class)<unknown> | The query whose result set size to calculate. | + +Returns: + +Promise<[AggregateQuerySnapshot](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<{ count: [AggregateField](./firestore_.aggregatefield.md#aggregatefield_class)<number>; }>> + +A Promise that will be resolved with the count; the count can be retrieved from `snapshot.data().count`, where `snapshot` is the `AggregateQuerySnapshot` to which the returned Promise resolves. + +## getDocs() + +Executes the query and returns the results as a `QuerySnapshot`. + +Note: `getDocs()` attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. To specify this behavior, invoke [getDocsFromCache()](./firestore_.md#getdocsfromcache) or [getDocsFromServer()](./firestore_.md#getdocsfromserver). + +Signature: + +```typescript +export declare function getDocs(query: Query): Promise>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./firestore_.query.md#query_class)<T> | | + +Returns: + +Promise<[QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>> + +A `Promise` that will be resolved with the results of the query. + +## getDocsFromCache() + +Executes the query and returns the results as a `QuerySnapshot` from cache. Returns an empty result set if no documents matching the query are currently cached. + +Signature: + +```typescript +export declare function getDocsFromCache(query: Query): Promise>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./firestore_.query.md#query_class)<T> | | + +Returns: + +Promise<[QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>> + +A `Promise` that will be resolved with the results of the query. + +## getDocsFromServer() + +Executes the query and returns the results as a `QuerySnapshot` from the server. Returns an error if the network is not available. + +Signature: + +```typescript +export declare function getDocsFromServer(query: Query): Promise>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./firestore_.query.md#query_class)<T> | | + +Returns: + +Promise<[QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>> + +A `Promise` that will be resolved with the results of the query. + +## onSnapshot() + +Attaches a listener for `QuerySnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. The listener can be cancelled by calling the function that is returned when `onSnapshot` is called. + +NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. + +Signature: + +```typescript +export declare function onSnapshot(query: Query, observer: { + next?: (snapshot: QuerySnapshot) => void; + error?: (error: FirestoreError) => void; + complete?: () => void; +}): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./firestore_.query.md#query_class)<T> | The query to listen to. | +| observer | { next?: (snapshot: [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>) => void; error?: (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void; complete?: () => void; } | A single object containing next and error callbacks. | + +Returns: + +[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) + +An unsubscribe function that can be called to cancel the snapshot listener. + +## onSnapshot() + +Attaches a listener for `QuerySnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. The listener can be cancelled by calling the function that is returned when `onSnapshot` is called. + +NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. + +Signature: + +```typescript +export declare function onSnapshot(query: Query, options: SnapshotListenOptions, observer: { + next?: (snapshot: QuerySnapshot) => void; + error?: (error: FirestoreError) => void; + complete?: () => void; +}): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./firestore_.query.md#query_class)<T> | The query to listen to. | +| options | [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | Options controlling the listen behavior. | +| observer | { next?: (snapshot: [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>) => void; error?: (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void; complete?: () => void; } | A single object containing next and error callbacks. | + +Returns: + +[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) + +An unsubscribe function that can be called to cancel the snapshot listener. + +## onSnapshot() + +Attaches a listener for `QuerySnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. The listener can be cancelled by calling the function that is returned when `onSnapshot` is called. + +NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. + +Signature: + +```typescript +export declare function onSnapshot(query: Query, onNext: (snapshot: QuerySnapshot) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./firestore_.query.md#query_class)<T> | The query to listen to. | +| onNext | (snapshot: [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>) => void | A callback to be called every time a new QuerySnapshot is available. | +| onError | (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void | A callback to be called if the listen fails or is cancelled. No further callbacks will occur. | +| onCompletion | () => void | Can be provided, but will not be called since streams are never ending. | + +Returns: + +[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) + +An unsubscribe function that can be called to cancel the snapshot listener. + +## onSnapshot() + +Attaches a listener for `QuerySnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. The listener can be cancelled by calling the function that is returned when `onSnapshot` is called. + +NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. + +Signature: + +```typescript +export declare function onSnapshot(query: Query, options: SnapshotListenOptions, onNext: (snapshot: QuerySnapshot) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./firestore_.query.md#query_class)<T> | The query to listen to. | +| options | [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | Options controlling the listen behavior. | +| onNext | (snapshot: [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>) => void | A callback to be called every time a new QuerySnapshot is available. | +| onError | (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void | A callback to be called if the listen fails or is cancelled. No further callbacks will occur. | +| onCompletion | () => void | Can be provided, but will not be called since streams are never ending. | + +Returns: + +[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) + +An unsubscribe function that can be called to cancel the snapshot listener. + +## query() + +Creates a new immutable instance of [Query](./firestore_.query.md#query_class) that is extended to also include additional query constraints. + +Signature: + +```typescript +export declare function query(query: Query, ...queryConstraints: QueryConstraint[]): Query; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./firestore_.query.md#query_class)<T> | The [Query](./firestore_.query.md#query_class) instance to use as a base for the new constraints. | +| queryConstraints | [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class)\[\] | The list of [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class)s to apply. | + +Returns: + +[Query](./firestore_.query.md#query_class)<T> + +## Exceptions + +if any of the provided query constraints cannot be combined with the existing or new constraints. + +## addDoc() + +Add a new document to specified `CollectionReference` with the given data, assigning it a document ID automatically. + +Signature: + +```typescript +export declare function addDoc(reference: CollectionReference, data: WithFieldValue): Promise>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | A reference to the collection to add this document to. | +| data | [WithFieldValue](./firestore_.md#withfieldvalue)<T> | An Object containing the data for the new document. | + +Returns: + +Promise<[DocumentReference](./firestore_.documentreference.md#documentreference_class)<T>> + +A `Promise` resolved with a `DocumentReference` pointing to the newly created document after it has been written to the backend (Note that it won't resolve while you're offline). + +## collection() + +Gets a `CollectionReference` instance that refers to a subcollection of `reference` at the the specified relative path. + +Signature: + +```typescript +export declare function collection(reference: CollectionReference, path: string, ...pathSegments: string[]): CollectionReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<unknown> | A reference to a collection. | +| path | string | A slash-separated path to a collection. | +| pathSegments | string\[\] | Additional path segments to apply relative to the first argument. | + +Returns: + +[CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> + +The `CollectionReference` instance. + +## Exceptions + +If the final path has an even number of segments and does not point to a collection. + +## collection() + +Gets a `CollectionReference` instance that refers to a subcollection of `reference` at the the specified relative path. + +Signature: + +```typescript +export declare function collection(reference: DocumentReference, path: string, ...pathSegments: string[]): CollectionReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class) | A reference to a Firestore document. | +| path | string | A slash-separated path to a collection. | +| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | + +Returns: + +[CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> + +The `CollectionReference` instance. + +## Exceptions + +If the final path has an even number of segments and does not point to a collection. + +## deleteDoc() + +Deletes the document referred to by the specified `DocumentReference`. + +Signature: + +```typescript +export declare function deleteDoc(reference: DocumentReference): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to the document to delete. | + +Returns: + +Promise<void> + +A Promise resolved once the document has been successfully deleted from the backend (note that it won't resolve while you're offline). + +## doc() + +Gets a `DocumentReference` instance that refers to a document within `reference` at the specified relative path. If no path is specified, an automatically-generated unique ID will be used for the returned `DocumentReference`. + +Signature: + +```typescript +export declare function doc(reference: CollectionReference, path?: string, ...pathSegments: string[]): DocumentReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | A reference to a collection. | +| path | string | A slash-separated path to a document. Has to be omitted to use auto-genrated IDs. | +| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | + +Returns: + +[DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> + +The `DocumentReference` instance. + +## Exceptions + +If the final path has an odd number of segments and does not point to a document. + +## doc() + +Gets a `DocumentReference` instance that refers to a document within `reference` at the specified relative path. + +Signature: + +```typescript +export declare function doc(reference: DocumentReference, path: string, ...pathSegments: string[]): DocumentReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to a Firestore document. | +| path | string | A slash-separated path to a document. | +| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | + +Returns: + +[DocumentReference](./firestore_.documentreference.md#documentreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> + +The `DocumentReference` instance. + +## Exceptions + +If the final path has an odd number of segments and does not point to a document. + +## getDoc() + +Reads the document referred to by this `DocumentReference`. + +Note: `getDoc()` attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. To specify this behavior, invoke [getDocFromCache()](./firestore_.md#getdocfromcache) or [getDocFromServer()](./firestore_.md#getdocfromserver). + +Signature: + +```typescript +export declare function getDoc(reference: DocumentReference): Promise>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | The reference of the document to fetch. | + +Returns: + +Promise<[DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>> + +A Promise resolved with a `DocumentSnapshot` containing the current document contents. + +## getDocFromCache() + +Reads the document referred to by this `DocumentReference` from cache. Returns an error if the document is not currently cached. + +Signature: + +```typescript +export declare function getDocFromCache(reference: DocumentReference): Promise>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | | + +Returns: + +Promise<[DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>> + +A `Promise` resolved with a `DocumentSnapshot` containing the current document contents. + +## getDocFromServer() + +Reads the document referred to by this `DocumentReference` from the server. Returns an error if the network is not available. + +Signature: + +```typescript +export declare function getDocFromServer(reference: DocumentReference): Promise>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | | + +Returns: + +Promise<[DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>> + +A `Promise` resolved with a `DocumentSnapshot` containing the current document contents. + +## onSnapshot() + +Attaches a listener for `DocumentSnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. + +NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. + +Signature: + +```typescript +export declare function onSnapshot(reference: DocumentReference, observer: { + next?: (snapshot: DocumentSnapshot) => void; + error?: (error: FirestoreError) => void; + complete?: () => void; +}): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to listen to. | +| observer | { next?: (snapshot: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>) => void; error?: (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void; complete?: () => void; } | A single object containing next and error callbacks. | + +Returns: + +[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) + +An unsubscribe function that can be called to cancel the snapshot listener. + +## onSnapshot() + +Attaches a listener for `DocumentSnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. + +NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. + +Signature: + +```typescript +export declare function onSnapshot(reference: DocumentReference, options: SnapshotListenOptions, observer: { + next?: (snapshot: DocumentSnapshot) => void; + error?: (error: FirestoreError) => void; + complete?: () => void; +}): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to listen to. | +| options | [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | Options controlling the listen behavior. | +| observer | { next?: (snapshot: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>) => void; error?: (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void; complete?: () => void; } | A single object containing next and error callbacks. | + +Returns: + +[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) + +An unsubscribe function that can be called to cancel the snapshot listener. + +## onSnapshot() + +Attaches a listener for `DocumentSnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. + +NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. + +Signature: + +```typescript +export declare function onSnapshot(reference: DocumentReference, onNext: (snapshot: DocumentSnapshot) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to listen to. | +| onNext | (snapshot: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>) => void | A callback to be called every time a new DocumentSnapshot is available. | +| onError | (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void | A callback to be called if the listen fails or is cancelled. No further callbacks will occur. | +| onCompletion | () => void | Can be provided, but will not be called since streams are never ending. | + +Returns: + +[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) + +An unsubscribe function that can be called to cancel the snapshot listener. + +## onSnapshot() + +Attaches a listener for `DocumentSnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. + +NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. + +Signature: + +```typescript +export declare function onSnapshot(reference: DocumentReference, options: SnapshotListenOptions, onNext: (snapshot: DocumentSnapshot) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to listen to. | +| options | [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | Options controlling the listen behavior. | +| onNext | (snapshot: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>) => void | A callback to be called every time a new DocumentSnapshot is available. | +| onError | (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void | A callback to be called if the listen fails or is cancelled. No further callbacks will occur. | +| onCompletion | () => void | Can be provided, but will not be called since streams are never ending. | + +Returns: + +[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) + +An unsubscribe function that can be called to cancel the snapshot listener. + +## setDoc() + +Writes to the document referred to by this `DocumentReference`. If the document does not yet exist, it will be created. + +Signature: + +```typescript +export declare function setDoc(reference: DocumentReference, data: WithFieldValue): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to write. | +| data | [WithFieldValue](./firestore_.md#withfieldvalue)<T> | A map of the fields and values for the document. | + +Returns: + +Promise<void> + +A `Promise` resolved once the data has been successfully written to the backend (note that it won't resolve while you're offline). + +## setDoc() + +Writes to the document referred to by the specified `DocumentReference`. If the document does not yet exist, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. + +Signature: + +```typescript +export declare function setDoc(reference: DocumentReference, data: PartialWithFieldValue, options: SetOptions): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to write. | +| data | [PartialWithFieldValue](./firestore_.md#partialwithfieldvalue)<T> | A map of the fields and values for the document. | +| options | [SetOptions](./firestore_.md#setoptions) | An object to configure the set behavior. | + +Returns: + +Promise<void> + +A Promise resolved once the data has been successfully written to the backend (note that it won't resolve while you're offline). + +## updateDoc() + +Updates fields in the document referred to by the specified `DocumentReference`. The update will fail if applied to a document that does not exist. + +Signature: + +```typescript +export declare function updateDoc(reference: DocumentReference, data: UpdateData): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to update. | +| data | [UpdateData](./firestore_.md#updatedata)<T> | An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document. | + +Returns: + +Promise<void> + +A `Promise` resolved once the data has been successfully written to the backend (note that it won't resolve while you're offline). + +## updateDoc() + +Updates fields in the document referred to by the specified `DocumentReference` The update will fail if applied to a document that does not exist. + +Nested fields can be updated by providing dot-separated field path strings or by providing `FieldPath` objects. + +Signature: + +```typescript +export declare function updateDoc(reference: DocumentReference, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to the document to update. | +| field | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The first field to update. | +| value | unknown | The first value. | +| moreFieldsAndValues | unknown\[\] | Additional key value pairs. | + +Returns: + +Promise<void> + +A `Promise` resolved once the data has been successfully written to the backend (note that it won't resolve while you're offline). + +## endAt() + +Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided document (inclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. + +Signature: + +```typescript +export declare function endAt(snapshot: DocumentSnapshot): QueryEndAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| snapshot | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to end at. | + +Returns: + +[QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) + +A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` + +## endBefore() + +Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. + +Signature: + +```typescript +export declare function endBefore(snapshot: DocumentSnapshot): QueryEndAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| snapshot | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to end before. | + +Returns: + +[QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) + +A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` + +## startAfter() + +Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. + +Signature: + +```typescript +export declare function startAfter(snapshot: DocumentSnapshot): QueryStartAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| snapshot | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to start after. | + +Returns: + +[QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) + +A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()` + +## startAt() + +Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the `orderBy` of this query. + +Signature: + +```typescript +export declare function startAt(snapshot: DocumentSnapshot): QueryStartAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| snapshot | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to start at. | + +Returns: + +[QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) + +A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()`. + +## CACHE\_SIZE\_UNLIMITED + +Constant used to indicate the LRU garbage collection should be disabled. Set this value as the `cacheSizeBytes` on the settings passed to the [Firestore](./firestore_.firestore.md#firestore_class) instance. + +Signature: + +```typescript +CACHE_SIZE_UNLIMITED = -1 +``` + +## AddPrefixToKeys + +Returns a new map where every key is prefixed with the outer key appended to a dot. + +Signature: + +```typescript +export declare type AddPrefixToKeys> = { + [K in keyof T & string as `${Prefix}.${K}`]+?: T[K]; +}; +``` + +## AggregateFieldType + +The union of all `AggregateField` types that are supported by Firestore. + +Signature: + +```typescript +export declare type AggregateFieldType = AggregateField; +``` + +## AggregateSpecData + +A type whose keys are taken from an `AggregateSpec`, and whose values are the result of the aggregation performed by the corresponding `AggregateField` from the input `AggregateSpec`. + +Signature: + +```typescript +export declare type AggregateSpecData = { + [P in keyof T]: T[P] extends AggregateField ? U : never; +}; +``` + +## ChildUpdateFields + +Helper for calculating the nested fields for a given type T1. This is needed to distribute union types such as `undefined | {...}` (happens for optional props) or `{a: A} | {b: B}`. + +In this use case, `V` is used to distribute the union types of `T[K]` on `Record`, since `T[K]` is evaluated as an expression and not distributed. + +See https://www.typescriptlang.org/docs/handbook/advanced-types.html\#distributive-conditional-types + +Signature: + +```typescript +export declare type ChildUpdateFields = V extends Record ? AddPrefixToKeys> : never; +``` + +## DocumentChangeType + +The type of a `DocumentChange` may be 'added', 'removed', or 'modified'. + +Signature: + +```typescript +export declare type DocumentChangeType = 'added' | 'removed' | 'modified'; +``` + +## FirestoreErrorCode + +The set of Firestore status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.md + +Possible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (e.g. an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation. + +Signature: + +```typescript +export declare type FirestoreErrorCode = 'cancelled' | 'unknown' | 'invalid-argument' | 'deadline-exceeded' | 'not-found' | 'already-exists' | 'permission-denied' | 'resource-exhausted' | 'failed-precondition' | 'aborted' | 'out-of-range' | 'unimplemented' | 'internal' | 'unavailable' | 'data-loss' | 'unauthenticated'; +``` + +## NestedUpdateFields + +For each field (e.g. 'bar'), find all nested keys (e.g. {'bar.baz': T1, 'bar.qux': T2}). Intersect them together to make a single map containing all possible keys that are all marked as optional + +Signature: + +```typescript +export declare type NestedUpdateFields> = UnionToIntersection<{ + [K in keyof T & string]: ChildUpdateFields; +}[keyof T & string]>; +``` + +## OrderByDirection + +The direction of a [orderBy()](./firestore_.md#orderby) clause is specified as 'desc' or 'asc' (descending or ascending). + +Signature: + +```typescript +export declare type OrderByDirection = 'desc' | 'asc'; +``` + +## PartialWithFieldValue + +Similar to Typescript's `Partial`, but allows nested fields to be omitted and FieldValues to be passed in as property values. + +Signature: + +```typescript +export declare type PartialWithFieldValue = Partial | (T extends Primitive ? T : T extends {} ? { + [K in keyof T]?: PartialWithFieldValue | FieldValue; +} : never); +``` + +## Primitive + +Primitive types. + +Signature: + +```typescript +export declare type Primitive = string | number | boolean | undefined | null; +``` + +## QueryConstraintType + +Describes the different query constraints available in this SDK. + +Signature: + +```typescript +export declare type QueryConstraintType = 'where' | 'orderBy' | 'limit' | 'limitToLast' | 'startAt' | 'startAfter' | 'endAt' | 'endBefore'; +``` + +## QueryNonFilterConstraint + +`QueryNonFilterConstraint` is a helper union type that represents QueryConstraints which are used to narrow or order the set of documents, but that do not explicitly filter on a document field. `QueryNonFilterConstraint`s are created by invoking [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains the `QueryConstraint`. + +Signature: + +```typescript +export declare type QueryNonFilterConstraint = QueryOrderByConstraint | QueryLimitConstraint | QueryStartAtConstraint | QueryEndAtConstraint; +``` + +## SetOptions + +An options object that configures the behavior of [setDoc()](./firestore_lite.md#setdoc), and calls. These calls can be configured to perform granular merges instead of overwriting the target documents in their entirety by providing a `SetOptions` with `merge: true`. + +Signature: + +```typescript +export declare type SetOptions = { + readonly merge?: boolean; +} | { + readonly mergeFields?: Array; +}; +``` + +## 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. + +Signature: + +```typescript +export declare type TaskState = 'Error' | 'Running' | 'Success'; +``` + +## UnionToIntersection + +Given a union type `U = T1 | T2 | ...`, returns an intersected type `(T1 & T2 & ...)`. + +Uses distributive conditional types and inference from conditional types. This works because multiple candidates for the same type variable in contra-variant positions causes an intersection type to be inferred. https://www.typescriptlang.org/docs/handbook/advanced-types.html\#type-inference-in-conditional-types https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection-type + +Signature: + +```typescript +export declare type UnionToIntersection = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never; +``` + +## UpdateData + +Update data (for use with [updateDoc()](./firestore_.md#updatedoc)) that consists of field paths (e.g. 'foo' or 'foo.baz') mapped to values. Fields that contain dots reference nested fields within the document. FieldValues can be passed in as property values. + +Signature: + +```typescript +export declare type UpdateData = T extends Primitive ? T : T extends {} ? { + [K in keyof T]?: UpdateData | FieldValue; +} & NestedUpdateFields : Partial; +``` + +## WhereFilterOp + +Filter conditions in a [where()](./firestore_.md#where) clause are specified using the strings '&lt;', '&lt;=', '==', '!=', '&gt;=', '&gt;', 'array-contains', 'in', 'array-contains-any', and 'not-in'. + +Signature: + +```typescript +export declare type WhereFilterOp = '<' | '<=' | '==' | '!=' | '>=' | '>' | 'array-contains' | 'in' | 'array-contains-any' | 'not-in'; +``` + +## WithFieldValue + +Allows FieldValues to be passed in as a property value while maintaining type safety. + +Signature: + +```typescript +export declare type WithFieldValue = T | (T extends Primitive ? T : T extends {} ? { + [K in keyof T]: WithFieldValue | FieldValue; +} : never); +``` diff --git a/docs-devsite/firestore_.persistencesettings.md b/docs-devsite/firestore_.persistencesettings.md new file mode 100644 index 00000000000..c84cde1ed13 --- /dev/null +++ b/docs-devsite/firestore_.persistencesettings.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# PersistenceSettings interface +Settings that can be passed to `enableIndexedDbPersistence()` to configure Firestore persistence. + +Signature: + +```typescript +export declare interface PersistenceSettings +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [forceOwnership](./firestore_.persistencesettings.md#persistencesettingsforceownership) | boolean | Whether to force enable persistence for the client. This cannot be used with multi-tab synchronization and is primarily intended for use with Web Workers. Setting this to true will enable persistence, but cause other tabs using persistence to fail. | + +## PersistenceSettings.forceOwnership + +Whether to force enable persistence for the client. This cannot be used with multi-tab synchronization and is primarily intended for use with Web Workers. Setting this to `true` will enable persistence, but cause other tabs using persistence to fail. + +Signature: + +```typescript +forceOwnership?: boolean; +``` diff --git a/docs-devsite/firestore_.query.md b/docs-devsite/firestore_.query.md new file mode 100644 index 00000000000..1961c2cc5f3 --- /dev/null +++ b/docs-devsite/firestore_.query.md @@ -0,0 +1,125 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Query class +A `Query` refers to a query which you can read or listen to. You can also construct refined `Query` objects by adding filters and ordering. + +Signature: + +```typescript +export declare class Query +``` + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)()](./firestore_.query.md#queryconstructor) | | Constructs a new instance of the Query class | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [converter](./firestore_.query.md#queryconverter) | | [FirestoreDataConverter](./firestore_.firestoredataconverter.md#firestoredataconverter_interface)<T> \| null | If provided, the FirestoreDataConverter associated with this instance. | +| [firestore](./firestore_.query.md#queryfirestore) | | [Firestore](./firestore_.firestore.md#firestore_class) | The Firestore instance for the Firestore database (useful for performing transactions, etc.). | +| [type](./firestore_.query.md#querytype) | | 'query' \| 'collection' | The type of this Firestore reference. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [withConverter(converter)](./firestore_.query.md#querywithconverter) | | Removes the current converter. | +| [withConverter(converter)](./firestore_.query.md#querywithconverter) | | Applies a custom data converter to this query, allowing you to use your own custom model objects with Firestore. When you call [getDocs()](./firestore_.md#getdocs) with the returned query, the provided converter will convert between Firestore data and your custom type U. | + +## Query.(constructor) + +Constructs a new instance of the `Query` class + +Signature: + +```typescript +protected constructor(); +``` + +## Query.converter + +If provided, the `FirestoreDataConverter` associated with this instance. + +Signature: + +```typescript +readonly converter: FirestoreDataConverter | null; +``` + +## Query.firestore + +The `Firestore` instance for the Firestore database (useful for performing transactions, etc.). + +Signature: + +```typescript +readonly firestore: Firestore; +``` + +## Query.type + +The type of this Firestore reference. + +Signature: + +```typescript +readonly type: 'query' | 'collection'; +``` + +## Query.withConverter() + +Removes the current converter. + +Signature: + +```typescript +withConverter(converter: null): Query; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| converter | null | null removes the current converter. | + +Returns: + +[Query](./firestore_.query.md#query_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> + +A `Query` that does not use a converter. + +## Query.withConverter() + +Applies a custom data converter to this query, allowing you to use your own custom model objects with Firestore. When you call [getDocs()](./firestore_.md#getdocs) with the returned query, the provided converter will convert between Firestore data and your custom type `U`. + +Signature: + +```typescript +withConverter(converter: FirestoreDataConverter): Query; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| converter | [FirestoreDataConverter](./firestore_.firestoredataconverter.md#firestoredataconverter_interface)<U> | Converts objects to and from Firestore. | + +Returns: + +[Query](./firestore_.query.md#query_class)<U> + +A `Query` that uses the provided converter. + diff --git a/docs-devsite/firestore_.queryconstraint.md b/docs-devsite/firestore_.queryconstraint.md new file mode 100644 index 00000000000..77ebddf1c65 --- /dev/null +++ b/docs-devsite/firestore_.queryconstraint.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryConstraint class +A `QueryConstraint` is used to narrow the set of documents returned by a Firestore query. `QueryConstraint`s are created by invoking [where()](./firestore_.md#where), [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit), [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryConstraint`. + +Signature: + +```typescript +export declare abstract class QueryConstraint +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_.queryconstraint.md#queryconstrainttype) | | [QueryConstraintType](./firestore_.md#queryconstrainttype) | The type of this query constraint | + +## QueryConstraint.type + +The type of this query constraint + +Signature: + +```typescript +abstract readonly type: QueryConstraintType; +``` diff --git a/docs-devsite/firestore_.querydocumentsnapshot.md b/docs-devsite/firestore_.querydocumentsnapshot.md new file mode 100644 index 00000000000..0755a11915f --- /dev/null +++ b/docs-devsite/firestore_.querydocumentsnapshot.md @@ -0,0 +1,54 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryDocumentSnapshot class +A `QueryDocumentSnapshot` contains data read from a document in your Firestore database as part of a query. The document is guaranteed to exist and its data can be extracted with `.data()` or `.get()` to get a specific field. + +A `QueryDocumentSnapshot` offers the same API surface as a `DocumentSnapshot`. Since query results contain only existing documents, the `exists` property will always be true and `data()` will never return 'undefined'. + +Signature: + +```typescript +export declare class QueryDocumentSnapshot extends DocumentSnapshot +``` +Extends: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T> + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [data(options)](./firestore_.querydocumentsnapshot.md#querydocumentsnapshotdata) | | Retrieves all fields in the document as an Object.By default, serverTimestamp() values that have not yet been set to their final value will be returned as null. You can override this by passing an options object. | + +## QueryDocumentSnapshot.data() + +Retrieves all fields in the document as an `Object`. + +By default, `serverTimestamp()` values that have not yet been set to their final value will be returned as `null`. You can override this by passing an options object. + +Signature: + +```typescript +/** @override */ +data(options?: SnapshotOptions): T; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| options | [SnapshotOptions](./firestore_.snapshotoptions.md#snapshotoptions_interface) | An options object to configure how data is retrieved from the snapshot (for example the desired behavior for server timestamps that have not yet been set to their final value). | + +Returns: + +T + +An `Object` containing all fields in the document. + diff --git a/docs-devsite/firestore_.queryendatconstraint.md b/docs-devsite/firestore_.queryendatconstraint.md new file mode 100644 index 00000000000..44dcddab71b --- /dev/null +++ b/docs-devsite/firestore_.queryendatconstraint.md @@ -0,0 +1,36 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryEndAtConstraint class +A `QueryEndAtConstraint` is used to exclude documents from the end of a result set returned by a Firestore query. `QueryEndAtConstraint`s are created by invoking [endAt()](./firestore_.md#endat) or [endBefore()](./firestore_.md#endbefore) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryEndAtConstraint`. + +Signature: + +```typescript +export declare class QueryEndAtConstraint extends QueryConstraint +``` +Extends: [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_.queryendatconstraint.md#queryendatconstrainttype) | | 'endBefore' \| 'endAt' | The type of this query constraint | + +## QueryEndAtConstraint.type + +The type of this query constraint + +Signature: + +```typescript +readonly type: 'endBefore' | 'endAt'; +``` diff --git a/docs-devsite/firestore_.queryfieldfilterconstraint.md b/docs-devsite/firestore_.queryfieldfilterconstraint.md new file mode 100644 index 00000000000..18710b6aa99 --- /dev/null +++ b/docs-devsite/firestore_.queryfieldfilterconstraint.md @@ -0,0 +1,36 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryFieldFilterConstraint class +A `QueryFieldFilterConstraint` is used to narrow the set of documents returned by a Firestore query by filtering on one or more document fields. `QueryFieldFilterConstraint`s are created by invoking [where()](./firestore_.md#where) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryFieldFilterConstraint`. + +Signature: + +```typescript +export declare class QueryFieldFilterConstraint extends QueryConstraint +``` +Extends: [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstrainttype) | | (not declared) | The type of this query constraint | + +## QueryFieldFilterConstraint.type + +The type of this query constraint + +Signature: + +```typescript +readonly type = "where"; +``` diff --git a/docs-devsite/firestore_.querylimitconstraint.md b/docs-devsite/firestore_.querylimitconstraint.md new file mode 100644 index 00000000000..72b06d61073 --- /dev/null +++ b/docs-devsite/firestore_.querylimitconstraint.md @@ -0,0 +1,36 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryLimitConstraint class +A `QueryLimitConstraint` is used to limit the number of documents returned by a Firestore query. `QueryLimitConstraint`s are created by invoking [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryLimitConstraint`. + +Signature: + +```typescript +export declare class QueryLimitConstraint extends QueryConstraint +``` +Extends: [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_.querylimitconstraint.md#querylimitconstrainttype) | | 'limit' \| 'limitToLast' | The type of this query constraint | + +## QueryLimitConstraint.type + +The type of this query constraint + +Signature: + +```typescript +readonly type: 'limit' | 'limitToLast'; +``` diff --git a/docs-devsite/firestore_.queryorderbyconstraint.md b/docs-devsite/firestore_.queryorderbyconstraint.md new file mode 100644 index 00000000000..6f24ac985dd --- /dev/null +++ b/docs-devsite/firestore_.queryorderbyconstraint.md @@ -0,0 +1,38 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryOrderByConstraint class +A `QueryOrderByConstraint` is used to sort the set of documents returned by a Firestore query. `QueryOrderByConstraint`s are created by invoking [orderBy()](./firestore_.md#orderby) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryOrderByConstraint`. + +Note: Documents that do not contain the orderBy field will not be present in the query result. + +Signature: + +```typescript +export declare class QueryOrderByConstraint extends QueryConstraint +``` +Extends: [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_.queryorderbyconstraint.md#queryorderbyconstrainttype) | | (not declared) | The type of this query constraint | + +## QueryOrderByConstraint.type + +The type of this query constraint + +Signature: + +```typescript +readonly type = "orderBy"; +``` diff --git a/docs-devsite/firestore_.querysnapshot.md b/docs-devsite/firestore_.querysnapshot.md new file mode 100644 index 00000000000..0abb869c003 --- /dev/null +++ b/docs-devsite/firestore_.querysnapshot.md @@ -0,0 +1,128 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QuerySnapshot class +A `QuerySnapshot` contains zero or more `DocumentSnapshot` objects representing the results of a query. The documents can be accessed as an array via the `docs` property or enumerated using the `forEach` method. The number of documents can be determined via the `empty` and `size` properties. + +Signature: + +```typescript +export declare class QuerySnapshot +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [docs](./firestore_.querysnapshot.md#querysnapshotdocs) | | Array<[QueryDocumentSnapshot](./firestore_.querydocumentsnapshot.md#querydocumentsnapshot_class)<T>> | An array of all the documents in the QuerySnapshot. | +| [empty](./firestore_.querysnapshot.md#querysnapshotempty) | | boolean | True if there are no documents in the QuerySnapshot. | +| [metadata](./firestore_.querysnapshot.md#querysnapshotmetadata) | | [SnapshotMetadata](./firestore_.snapshotmetadata.md#snapshotmetadata_class) | Metadata about this snapshot, concerning its source and if it has local modifications. | +| [query](./firestore_.querysnapshot.md#querysnapshotquery) | | [Query](./firestore_.query.md#query_class)<T> | The query on which you called get or onSnapshot in order to get this QuerySnapshot. | +| [size](./firestore_.querysnapshot.md#querysnapshotsize) | | number | The number of documents in the QuerySnapshot. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [docChanges(options)](./firestore_.querysnapshot.md#querysnapshotdocchanges) | | Returns an array of the documents changes since the last snapshot. If this is the first snapshot, all documents will be in the list as 'added' changes. | +| [forEach(callback, thisArg)](./firestore_.querysnapshot.md#querysnapshotforeach) | | Enumerates all of the documents in the QuerySnapshot. | + +## QuerySnapshot.docs + +An array of all the documents in the `QuerySnapshot`. + +Signature: + +```typescript +get docs(): Array>; +``` + +## QuerySnapshot.empty + +True if there are no documents in the `QuerySnapshot`. + +Signature: + +```typescript +get empty(): boolean; +``` + +## QuerySnapshot.metadata + +Metadata about this snapshot, concerning its source and if it has local modifications. + +Signature: + +```typescript +readonly metadata: SnapshotMetadata; +``` + +## QuerySnapshot.query + +The query on which you called `get` or `onSnapshot` in order to get this `QuerySnapshot`. + +Signature: + +```typescript +readonly query: Query; +``` + +## QuerySnapshot.size + +The number of documents in the `QuerySnapshot`. + +Signature: + +```typescript +get size(): number; +``` + +## QuerySnapshot.docChanges() + +Returns an array of the documents changes since the last snapshot. If this is the first snapshot, all documents will be in the list as 'added' changes. + +Signature: + +```typescript +docChanges(options?: SnapshotListenOptions): Array>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| options | [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | SnapshotListenOptions that control whether metadata-only changes (i.e. only DocumentSnapshot.metadata changed) should trigger snapshot events. | + +Returns: + +Array<[DocumentChange](./firestore_.documentchange.md#documentchange_interface)<T>> + +## QuerySnapshot.forEach() + +Enumerates all of the documents in the `QuerySnapshot`. + +Signature: + +```typescript +forEach(callback: (result: QueryDocumentSnapshot) => void, thisArg?: unknown): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| callback | (result: [QueryDocumentSnapshot](./firestore_.querydocumentsnapshot.md#querydocumentsnapshot_class)<T>) => void | A callback to be called with a QueryDocumentSnapshot for each document in the snapshot. | +| thisArg | unknown | The this binding for the callback. | + +Returns: + +void + diff --git a/docs-devsite/firestore_.querystartatconstraint.md b/docs-devsite/firestore_.querystartatconstraint.md new file mode 100644 index 00000000000..edad47f66ee --- /dev/null +++ b/docs-devsite/firestore_.querystartatconstraint.md @@ -0,0 +1,36 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryStartAtConstraint class +A `QueryStartAtConstraint` is used to exclude documents from the start of a result set returned by a Firestore query. `QueryStartAtConstraint`s are created by invoking [startAt()](./firestore_.md#startat) or [startAfter()](./firestore_.md#startafter) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryStartAtConstraint`. + +Signature: + +```typescript +export declare class QueryStartAtConstraint extends QueryConstraint +``` +Extends: [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_.querystartatconstraint.md#querystartatconstrainttype) | | 'startAt' \| 'startAfter' | The type of this query constraint | + +## QueryStartAtConstraint.type + +The type of this query constraint + +Signature: + +```typescript +readonly type: 'startAt' | 'startAfter'; +``` diff --git a/docs-devsite/firestore_.snapshotlistenoptions.md b/docs-devsite/firestore_.snapshotlistenoptions.md new file mode 100644 index 00000000000..dba8308fc02 --- /dev/null +++ b/docs-devsite/firestore_.snapshotlistenoptions.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# SnapshotListenOptions interface +An options object that can be passed to [onSnapshot()](./firestore_.md#onsnapshot) and [QuerySnapshot.docChanges()](./firestore_.querysnapshot.md#querysnapshotdocchanges) to control which types of changes to include in the result set. + +Signature: + +```typescript +export declare interface SnapshotListenOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [includeMetadataChanges](./firestore_.snapshotlistenoptions.md#snapshotlistenoptionsincludemetadatachanges) | boolean | Include a change even if only the metadata of the query or of a document changed. Default is false. | + +## SnapshotListenOptions.includeMetadataChanges + +Include a change even if only the metadata of the query or of a document changed. Default is false. + +Signature: + +```typescript +readonly includeMetadataChanges?: boolean; +``` diff --git a/docs-devsite/firestore_.snapshotmetadata.md b/docs-devsite/firestore_.snapshotmetadata.md new file mode 100644 index 00000000000..6f062ed1c92 --- /dev/null +++ b/docs-devsite/firestore_.snapshotmetadata.md @@ -0,0 +1,75 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# SnapshotMetadata class +Metadata about a snapshot, describing the state of the snapshot. + +Signature: + +```typescript +export declare class SnapshotMetadata +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [fromCache](./firestore_.snapshotmetadata.md#snapshotmetadatafromcache) | | boolean | True if the snapshot was created from cached data rather than guaranteed up-to-date server data. If your listener has opted into metadata updates (via SnapshotListenOptions) you will receive another snapshot with fromCache set to false once the client has received up-to-date data from the backend. | +| [hasPendingWrites](./firestore_.snapshotmetadata.md#snapshotmetadatahaspendingwrites) | | boolean | True if the snapshot contains the result of local writes (for example set() or update() calls) that have not yet been committed to the backend. If your listener has opted into metadata updates (via SnapshotListenOptions) you will receive another snapshot with hasPendingWrites equal to false once the writes have been committed to the backend. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [isEqual(other)](./firestore_.snapshotmetadata.md#snapshotmetadataisequal) | | Returns true if this SnapshotMetadata is equal to the provided one. | + +## SnapshotMetadata.fromCache + +True if the snapshot was created from cached data rather than guaranteed up-to-date server data. If your listener has opted into metadata updates (via `SnapshotListenOptions`) you will receive another snapshot with `fromCache` set to false once the client has received up-to-date data from the backend. + +Signature: + +```typescript +readonly fromCache: boolean; +``` + +## SnapshotMetadata.hasPendingWrites + +True if the snapshot contains the result of local writes (for example `set()` or `update()` calls) that have not yet been committed to the backend. If your listener has opted into metadata updates (via `SnapshotListenOptions`) you will receive another snapshot with `hasPendingWrites` equal to false once the writes have been committed to the backend. + +Signature: + +```typescript +readonly hasPendingWrites: boolean; +``` + +## SnapshotMetadata.isEqual() + +Returns true if this `SnapshotMetadata` is equal to the provided one. + +Signature: + +```typescript +isEqual(other: SnapshotMetadata): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| other | [SnapshotMetadata](./firestore_.snapshotmetadata.md#snapshotmetadata_class) | The SnapshotMetadata to compare against. | + +Returns: + +boolean + +true if this `SnapshotMetadata` is equal to the provided one. + diff --git a/docs-devsite/firestore_.snapshotoptions.md b/docs-devsite/firestore_.snapshotoptions.md new file mode 100644 index 00000000000..e7ccd715552 --- /dev/null +++ b/docs-devsite/firestore_.snapshotoptions.md @@ -0,0 +1,41 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# SnapshotOptions interface +Options that configure how data is retrieved from a `DocumentSnapshot` (for example the desired behavior for server timestamps that have not yet been set to their final value). + +Signature: + +```typescript +export declare interface SnapshotOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [serverTimestamps](./firestore_.snapshotoptions.md#snapshotoptionsservertimestamps) | 'estimate' \| 'previous' \| 'none' | If set, controls the return value for server timestamps that have not yet been set to their final value.By specifying 'estimate', pending server timestamps return an estimate based on the local clock. This estimate will differ from the final value and cause these values to change once the server result becomes available.By specifying 'previous', pending timestamps will be ignored and return their previous value instead.If omitted or set to 'none', null will be returned by default until the server value becomes available. | + +## SnapshotOptions.serverTimestamps + +If set, controls the return value for server timestamps that have not yet been set to their final value. + +By specifying 'estimate', pending server timestamps return an estimate based on the local clock. This estimate will differ from the final value and cause these values to change once the server result becomes available. + +By specifying 'previous', pending timestamps will be ignored and return their previous value instead. + +If omitted or set to 'none', `null` will be returned by default until the server value becomes available. + +Signature: + +```typescript +readonly serverTimestamps?: 'estimate' | 'previous' | 'none'; +``` diff --git a/docs-devsite/firestore_.timestamp.md b/docs-devsite/firestore_.timestamp.md new file mode 100644 index 00000000000..ef75f07fdd5 --- /dev/null +++ b/docs-devsite/firestore_.timestamp.md @@ -0,0 +1,243 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Timestamp class +A `Timestamp` represents a point in time independent of any time zone or calendar, represented as seconds and fractions of seconds at nanosecond resolution in UTC Epoch time. + +It is encoded using the Proleptic Gregorian Calendar which extends the Gregorian calendar backwards to year one. It is encoded assuming all minutes are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. + +For examples and further specifications, refer to the [Timestamp definition](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto). + +Signature: + +```typescript +export declare class Timestamp +``` + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(seconds, nanoseconds)](./firestore_.timestamp.md#timestampconstructor) | | Creates a new timestamp. | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [nanoseconds](./firestore_.timestamp.md#timestampnanoseconds) | | number | The fractions of a second at nanosecond resolution.\* | +| [seconds](./firestore_.timestamp.md#timestampseconds) | | number | The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [fromDate(date)](./firestore_.timestamp.md#timestampfromdate) | static | Creates a new timestamp from the given date. | +| [fromMillis(milliseconds)](./firestore_.timestamp.md#timestampfrommillis) | static | Creates a new timestamp from the given number of milliseconds. | +| [isEqual(other)](./firestore_.timestamp.md#timestampisequal) | | Returns true if this Timestamp is equal to the provided one. | +| [now()](./firestore_.timestamp.md#timestampnow) | static | Creates a new timestamp with the current date, with millisecond precision. | +| [toDate()](./firestore_.timestamp.md#timestamptodate) | | Converts a Timestamp to a JavaScript Date object. This conversion causes a loss of precision since Date objects only support millisecond precision. | +| [toJSON()](./firestore_.timestamp.md#timestamptojson) | | Returns a JSON-serializable representation of this Timestamp. | +| [toMillis()](./firestore_.timestamp.md#timestamptomillis) | | Converts a Timestamp to a numeric timestamp (in milliseconds since epoch). This operation causes a loss of precision. | +| [toString()](./firestore_.timestamp.md#timestamptostring) | | Returns a textual representation of this Timestamp. | +| [valueOf()](./firestore_.timestamp.md#timestampvalueof) | | Converts this object to a primitive string, which allows Timestamp objects to be compared using the >, <=, >= and > operators. | + +## Timestamp.(constructor) + +Creates a new timestamp. + +Signature: + +```typescript +constructor( + seconds: number, + nanoseconds: number); +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| seconds | number | The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive. | +| nanoseconds | number | The non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanoseconds values that count forward in time. Must be from 0 to 999,999,999 inclusive. | + +## Timestamp.nanoseconds + +The fractions of a second at nanosecond resolution.\* + +Signature: + +```typescript +readonly nanoseconds: number; +``` + +## Timestamp.seconds + +The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. + +Signature: + +```typescript +readonly seconds: number; +``` + +## Timestamp.fromDate() + +Creates a new timestamp from the given date. + +Signature: + +```typescript +static fromDate(date: Date): Timestamp; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| date | Date | The date to initialize the Timestamp from. | + +Returns: + +[Timestamp](./firestore_.timestamp.md#timestamp_class) + +A new `Timestamp` representing the same point in time as the given date. + +## Timestamp.fromMillis() + +Creates a new timestamp from the given number of milliseconds. + +Signature: + +```typescript +static fromMillis(milliseconds: number): Timestamp; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| milliseconds | number | Number of milliseconds since Unix epoch 1970-01-01T00:00:00Z. | + +Returns: + +[Timestamp](./firestore_.timestamp.md#timestamp_class) + +A new `Timestamp` representing the same point in time as the given number of milliseconds. + +## Timestamp.isEqual() + +Returns true if this `Timestamp` is equal to the provided one. + +Signature: + +```typescript +isEqual(other: Timestamp): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| other | [Timestamp](./firestore_.timestamp.md#timestamp_class) | The Timestamp to compare against. | + +Returns: + +boolean + +true if this `Timestamp` is equal to the provided one. + +## Timestamp.now() + +Creates a new timestamp with the current date, with millisecond precision. + +Signature: + +```typescript +static now(): Timestamp; +``` +Returns: + +[Timestamp](./firestore_.timestamp.md#timestamp_class) + +a new timestamp representing the current date. + +## Timestamp.toDate() + +Converts a `Timestamp` to a JavaScript `Date` object. This conversion causes a loss of precision since `Date` objects only support millisecond precision. + +Signature: + +```typescript +toDate(): Date; +``` +Returns: + +Date + +JavaScript `Date` object representing the same point in time as this `Timestamp`, with millisecond precision. + +## Timestamp.toJSON() + +Returns a JSON-serializable representation of this `Timestamp`. + +Signature: + +```typescript +toJSON(): { + seconds: number; + nanoseconds: number; + }; +``` +Returns: + +{ seconds: number; nanoseconds: number; } + +## Timestamp.toMillis() + +Converts a `Timestamp` to a numeric timestamp (in milliseconds since epoch). This operation causes a loss of precision. + +Signature: + +```typescript +toMillis(): number; +``` +Returns: + +number + +The point in time corresponding to this timestamp, represented as the number of milliseconds since Unix epoch 1970-01-01T00:00:00Z. + +## Timestamp.toString() + +Returns a textual representation of this `Timestamp`. + +Signature: + +```typescript +toString(): string; +``` +Returns: + +string + +## Timestamp.valueOf() + +Converts this object to a primitive string, which allows `Timestamp` objects to be compared using the `>`, `<=`, `>=` and `>` operators. + +Signature: + +```typescript +valueOf(): string; +``` +Returns: + +string + diff --git a/docs-devsite/firestore_.transaction.md b/docs-devsite/firestore_.transaction.md new file mode 100644 index 00000000000..24f0690bea4 --- /dev/null +++ b/docs-devsite/firestore_.transaction.md @@ -0,0 +1,190 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Transaction class +A reference to a transaction. + +The `Transaction` object passed to a transaction's `updateFunction` provides the methods to read and write data within the transaction context. See [runTransaction()](./firestore_.md#runtransaction). + +Signature: + +```typescript +export declare class Transaction +``` + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [delete(documentRef)](./firestore_.transaction.md#transactiondelete) | | Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). | +| [get(documentRef)](./firestore_.transaction.md#transactionget) | | Reads the document referenced by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). | +| [set(documentRef, data)](./firestore_.transaction.md#transactionset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. | +| [set(documentRef, data, options)](./firestore_.transaction.md#transactionset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document. | +| [update(documentRef, data)](./firestore_.transaction.md#transactionupdate) | | Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. | +| [update(documentRef, field, value, moreFieldsAndValues)](./firestore_.transaction.md#transactionupdate) | | Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist.Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects. | + +## Transaction.delete() + +Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). + +Signature: + +```typescript +delete(documentRef: DocumentReference): this; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to the document to be deleted. | + +Returns: + +this + +This `Transaction` instance. Used for chaining method calls. + +## Transaction.get() + +Reads the document referenced by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). + +Signature: + +```typescript +get(documentRef: DocumentReference): Promise>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be read. | + +Returns: + +Promise<[DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>> + +A `DocumentSnapshot` with the read data. + +## Transaction.set() + +Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. + +Signature: + +```typescript +set(documentRef: DocumentReference, data: WithFieldValue): this; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | +| data | [WithFieldValue](./firestore_.md#withfieldvalue)<T> | An object of the fields and values for the document. | + +Returns: + +this + +This `Transaction` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not a valid Firestore document. + +## Transaction.set() + +Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. + +Signature: + +```typescript +set(documentRef: DocumentReference, data: PartialWithFieldValue, options: SetOptions): this; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | +| data | [PartialWithFieldValue](./firestore_.md#partialwithfieldvalue)<T> | An object of the fields and values for the document. | +| options | [SetOptions](./firestore_.md#setoptions) | An object to configure the set behavior. | + +Returns: + +this + +This `Transaction` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not a valid Firestore document. + +## Transaction.update() + +Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. + +Signature: + +```typescript +update(documentRef: DocumentReference, data: UpdateData): this; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be updated. | +| data | [UpdateData](./firestore_.md#updatedata)<T> | An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document. | + +Returns: + +this + +This `Transaction` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not valid Firestore data. + +## Transaction.update() + +Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. + +Nested fields can be updated by providing dot-separated field path strings or by providing `FieldPath` objects. + +Signature: + +```typescript +update(documentRef: DocumentReference, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): this; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to the document to be updated. | +| field | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The first field to update. | +| value | unknown | The first value. | +| moreFieldsAndValues | unknown\[\] | Additional key/value pairs. | + +Returns: + +this + +This `Transaction` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not valid Firestore data. + diff --git a/docs-devsite/firestore_.transactionoptions.md b/docs-devsite/firestore_.transactionoptions.md new file mode 100644 index 00000000000..1e7a5aedd28 --- /dev/null +++ b/docs-devsite/firestore_.transactionoptions.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# TransactionOptions interface +Options to customize transaction behavior. + +Signature: + +```typescript +export declare interface TransactionOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [maxAttempts](./firestore_.transactionoptions.md#transactionoptionsmaxattempts) | number | Maximum number of attempts to commit, after which transaction fails. Default is 5. | + +## TransactionOptions.maxAttempts + +Maximum number of attempts to commit, after which transaction fails. Default is 5. + +Signature: + +```typescript +readonly maxAttempts?: number; +``` diff --git a/docs-devsite/firestore_.unsubscribe.md b/docs-devsite/firestore_.unsubscribe.md new file mode 100644 index 00000000000..8bafb4f9ee8 --- /dev/null +++ b/docs-devsite/firestore_.unsubscribe.md @@ -0,0 +1,19 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Unsubscribe interface +A function returned by `onSnapshot()` that removes the listener when invoked. + +Signature: + +```typescript +export declare interface Unsubscribe +``` diff --git a/docs-devsite/firestore_.writebatch.md b/docs-devsite/firestore_.writebatch.md new file mode 100644 index 00000000000..878cb66810a --- /dev/null +++ b/docs-devsite/firestore_.writebatch.md @@ -0,0 +1,181 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# WriteBatch class +A write batch, used to perform multiple writes as a single atomic unit. + +A `WriteBatch` object can be acquired by calling [writeBatch()](./firestore_.md#writebatch). It provides methods for adding writes to the write batch. None of the writes will be committed (or visible locally) until [WriteBatch.commit()](./firestore_.writebatch.md#writebatchcommit) is called. + +Signature: + +```typescript +export declare class WriteBatch +``` + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [commit()](./firestore_.writebatch.md#writebatchcommit) | | Commits all of the writes in this write batch as a single atomic unit.The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | +| [delete(documentRef)](./firestore_.writebatch.md#writebatchdelete) | | Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). | +| [set(documentRef, data)](./firestore_.writebatch.md#writebatchset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. | +| [set(documentRef, data, options)](./firestore_.writebatch.md#writebatchset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document. | +| [update(documentRef, data)](./firestore_.writebatch.md#writebatchupdate) | | Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. | +| [update(documentRef, field, value, moreFieldsAndValues)](./firestore_.writebatch.md#writebatchupdate) | | Updates fields in the document referred to by this [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist.Nested fields can be update by providing dot-separated field path strings or by providing FieldPath objects. | + +## WriteBatch.commit() + +Commits all of the writes in this write batch as a single atomic unit. + +The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. + +Signature: + +```typescript +commit(): Promise; +``` +Returns: + +Promise<void> + +A `Promise` resolved once all of the writes in the batch have been successfully written to the backend as an atomic unit (note that it won't resolve while you're offline). + +## WriteBatch.delete() + +Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). + +Signature: + +```typescript +delete(documentRef: DocumentReference): WriteBatch; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to the document to be deleted. | + +Returns: + +[WriteBatch](./firestore_.writebatch.md#writebatch_class) + +This `WriteBatch` instance. Used for chaining method calls. + +## WriteBatch.set() + +Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. + +Signature: + +```typescript +set(documentRef: DocumentReference, data: WithFieldValue): WriteBatch; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | +| data | [WithFieldValue](./firestore_.md#withfieldvalue)<T> | An object of the fields and values for the document. | + +Returns: + +[WriteBatch](./firestore_.writebatch.md#writebatch_class) + +This `WriteBatch` instance. Used for chaining method calls. + +## WriteBatch.set() + +Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. + +Signature: + +```typescript +set(documentRef: DocumentReference, data: PartialWithFieldValue, options: SetOptions): WriteBatch; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | +| data | [PartialWithFieldValue](./firestore_.md#partialwithfieldvalue)<T> | An object of the fields and values for the document. | +| options | [SetOptions](./firestore_.md#setoptions) | An object to configure the set behavior. | + +Returns: + +[WriteBatch](./firestore_.writebatch.md#writebatch_class) + +This `WriteBatch` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not a valid Firestore document. + +## WriteBatch.update() + +Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. + +Signature: + +```typescript +update(documentRef: DocumentReference, data: UpdateData): WriteBatch; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be updated. | +| data | [UpdateData](./firestore_.md#updatedata)<T> | An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document. | + +Returns: + +[WriteBatch](./firestore_.writebatch.md#writebatch_class) + +This `WriteBatch` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not valid Firestore data. + +## WriteBatch.update() + +Updates fields in the document referred to by this [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. + +Nested fields can be update by providing dot-separated field path strings or by providing `FieldPath` objects. + +Signature: + +```typescript +update(documentRef: DocumentReference, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): WriteBatch; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to the document to be updated. | +| field | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The first field to update. | +| value | unknown | The first value. | +| moreFieldsAndValues | unknown\[\] | Additional key value pairs. | + +Returns: + +[WriteBatch](./firestore_.writebatch.md#writebatch_class) + +This `WriteBatch` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not valid Firestore data. + diff --git a/docs-devsite/firestore_lite.aggregatefield.md b/docs-devsite/firestore_lite.aggregatefield.md new file mode 100644 index 00000000000..952b60c9d80 --- /dev/null +++ b/docs-devsite/firestore_lite.aggregatefield.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AggregateField class +Represents an aggregation that can be performed by Firestore. + +Signature: + +```typescript +export declare class AggregateField +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_lite.aggregatefield.md#aggregatefieldtype) | | string | A type string to uniquely identify instances of this class. | + +## AggregateField.type + +A type string to uniquely identify instances of this class. + +Signature: + +```typescript +type: string; +``` diff --git a/docs-devsite/firestore_lite.aggregatequerysnapshot.md b/docs-devsite/firestore_lite.aggregatequerysnapshot.md new file mode 100644 index 00000000000..4b5d3120ba3 --- /dev/null +++ b/docs-devsite/firestore_lite.aggregatequerysnapshot.md @@ -0,0 +1,70 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AggregateQuerySnapshot class +The results of executing an aggregation query. + +Signature: + +```typescript +export declare class AggregateQuerySnapshot +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [query](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshotquery) | | [Query](./firestore_lite.query.md#query_class)<unknown> | The underlying query over which the aggregations recorded in this AggregateQuerySnapshot were performed. | +| [type](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshottype) | | (not declared) | A type string to uniquely identify instances of this class. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [data()](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshotdata) | | Returns the results of the aggregations performed over the underlying query.The keys of the returned object will be the same as those of the AggregateSpec object specified to the aggregation method, and the values will be the corresponding aggregation result. | + +## AggregateQuerySnapshot.query + +The underlying query over which the aggregations recorded in this `AggregateQuerySnapshot` were performed. + +Signature: + +```typescript +readonly query: Query; +``` + +## AggregateQuerySnapshot.type + +A type string to uniquely identify instances of this class. + +Signature: + +```typescript +readonly type = "AggregateQuerySnapshot"; +``` + +## AggregateQuerySnapshot.data() + +Returns the results of the aggregations performed over the underlying query. + +The keys of the returned object will be the same as those of the `AggregateSpec` object specified to the aggregation method, and the values will be the corresponding aggregation result. + +Signature: + +```typescript +data(): AggregateSpecData; +``` +Returns: + +[AggregateSpecData](./firestore_lite.md#aggregatespecdata)<T> + +The results of the aggregations performed over the underlying query. + diff --git a/docs-devsite/firestore_lite.aggregatespec.md b/docs-devsite/firestore_lite.aggregatespec.md new file mode 100644 index 00000000000..be06b6941f3 --- /dev/null +++ b/docs-devsite/firestore_lite.aggregatespec.md @@ -0,0 +1,19 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AggregateSpec interface +A type whose property values are all `AggregateField` objects. + +Signature: + +```typescript +export declare interface AggregateSpec +``` diff --git a/docs-devsite/firestore_lite.bytes.md b/docs-devsite/firestore_lite.bytes.md new file mode 100644 index 00000000000..8dec3bdd201 --- /dev/null +++ b/docs-devsite/firestore_lite.bytes.md @@ -0,0 +1,138 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Bytes class +An immutable object representing an array of bytes. + +Signature: + +```typescript +export declare class Bytes +``` + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [fromBase64String(base64)](./firestore_lite.bytes.md#bytesfrombase64string) | static | Creates a new Bytes object from the given Base64 string, converting it to bytes. | +| [fromUint8Array(array)](./firestore_lite.bytes.md#bytesfromuint8array) | static | Creates a new Bytes object from the given Uint8Array. | +| [isEqual(other)](./firestore_lite.bytes.md#bytesisequal) | | Returns true if this Bytes object is equal to the provided one. | +| [toBase64()](./firestore_lite.bytes.md#bytestobase64) | | Returns the underlying bytes as a Base64-encoded string. | +| [toString()](./firestore_lite.bytes.md#bytestostring) | | Returns a string representation of the Bytes object. | +| [toUint8Array()](./firestore_lite.bytes.md#bytestouint8array) | | Returns the underlying bytes in a new Uint8Array. | + +## Bytes.fromBase64String() + +Creates a new `Bytes` object from the given Base64 string, converting it to bytes. + +Signature: + +```typescript +static fromBase64String(base64: string): Bytes; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| base64 | string | The Base64 string used to create the Bytes object. | + +Returns: + +[Bytes](./firestore_lite.bytes.md#bytes_class) + +## Bytes.fromUint8Array() + +Creates a new `Bytes` object from the given Uint8Array. + +Signature: + +```typescript +static fromUint8Array(array: Uint8Array): Bytes; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| array | Uint8Array | The Uint8Array used to create the Bytes object. | + +Returns: + +[Bytes](./firestore_lite.bytes.md#bytes_class) + +## Bytes.isEqual() + +Returns true if this `Bytes` object is equal to the provided one. + +Signature: + +```typescript +isEqual(other: Bytes): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| other | [Bytes](./firestore_lite.bytes.md#bytes_class) | The Bytes object to compare against. | + +Returns: + +boolean + +true if this `Bytes` object is equal to the provided one. + +## Bytes.toBase64() + +Returns the underlying bytes as a Base64-encoded string. + +Signature: + +```typescript +toBase64(): string; +``` +Returns: + +string + +The Base64-encoded string created from the `Bytes` object. + +## Bytes.toString() + +Returns a string representation of the `Bytes` object. + +Signature: + +```typescript +toString(): string; +``` +Returns: + +string + +A string representation of the `Bytes` object. + +## Bytes.toUint8Array() + +Returns the underlying bytes in a new `Uint8Array`. + +Signature: + +```typescript +toUint8Array(): Uint8Array; +``` +Returns: + +Uint8Array + +The Uint8Array created from the `Bytes` object. + diff --git a/docs-devsite/firestore_lite.collectionreference.md b/docs-devsite/firestore_lite.collectionreference.md new file mode 100644 index 00000000000..d446560a02f --- /dev/null +++ b/docs-devsite/firestore_lite.collectionreference.md @@ -0,0 +1,121 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# CollectionReference class +A `CollectionReference` object can be used for adding documents, getting document references, and querying for documents (using [query()](./firestore_.md#query)). + +Signature: + +```typescript +export declare class CollectionReference extends Query +``` +Extends: [Query](./firestore_lite.query.md#query_class)<T> + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [id](./firestore_lite.collectionreference.md#collectionreferenceid) | | string | The collection's identifier. | +| [parent](./firestore_lite.collectionreference.md#collectionreferenceparent) | | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> \| null | A reference to the containing DocumentReference if this is a subcollection. If this isn't a subcollection, the reference is null. | +| [path](./firestore_lite.collectionreference.md#collectionreferencepath) | | string | A string representing the path of the referenced collection (relative to the root of the database). | +| [type](./firestore_lite.collectionreference.md#collectionreferencetype) | | (not declared) | The type of this Firestore reference. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [withConverter(converter)](./firestore_lite.collectionreference.md#collectionreferencewithconverter) | | Applies a custom data converter to this CollectionReference, allowing you to use your own custom model objects with Firestore. When you call [addDoc()](./firestore_.md#adddoc) with the returned CollectionReference instance, the provided converter will convert between Firestore data and your custom type U. | +| [withConverter(converter)](./firestore_lite.collectionreference.md#collectionreferencewithconverter) | | Removes the current converter. | + +## CollectionReference.id + +The collection's identifier. + +Signature: + +```typescript +get id(): string; +``` + +## CollectionReference.parent + +A reference to the containing `DocumentReference` if this is a subcollection. If this isn't a subcollection, the reference is null. + +Signature: + +```typescript +get parent(): DocumentReference | null; +``` + +## CollectionReference.path + +A string representing the path of the referenced collection (relative to the root of the database). + +Signature: + +```typescript +get path(): string; +``` + +## CollectionReference.type + +The type of this Firestore reference. + +Signature: + +```typescript +readonly type = "collection"; +``` + +## CollectionReference.withConverter() + +Applies a custom data converter to this `CollectionReference`, allowing you to use your own custom model objects with Firestore. When you call [addDoc()](./firestore_.md#adddoc) with the returned `CollectionReference` instance, the provided converter will convert between Firestore data and your custom type `U`. + +Signature: + +```typescript +withConverter(converter: FirestoreDataConverter): CollectionReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| converter | [FirestoreDataConverter](./firestore_lite.firestoredataconverter.md#firestoredataconverter_interface)<U> | Converts objects to and from Firestore. | + +Returns: + +[CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<U> + +A `CollectionReference` that uses the provided converter. + +## CollectionReference.withConverter() + +Removes the current converter. + +Signature: + +```typescript +withConverter(converter: null): CollectionReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| converter | null | null removes the current converter. | + +Returns: + +[CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> + +A `CollectionReference` that does not use a converter. + diff --git a/docs-devsite/firestore_lite.documentdata.md b/docs-devsite/firestore_lite.documentdata.md new file mode 100644 index 00000000000..09b5eb64b48 --- /dev/null +++ b/docs-devsite/firestore_lite.documentdata.md @@ -0,0 +1,19 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# DocumentData interface +Document data (for use with [setDoc()](./firestore_lite.md#setdoc)) consists of fields mapped to values. + +Signature: + +```typescript +export declare interface DocumentData +``` diff --git a/docs-devsite/firestore_lite.documentreference.md b/docs-devsite/firestore_lite.documentreference.md new file mode 100644 index 00000000000..0e307435949 --- /dev/null +++ b/docs-devsite/firestore_lite.documentreference.md @@ -0,0 +1,142 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# DocumentReference class +A `DocumentReference` refers to a document location in a Firestore database and can be used to write, read, or listen to the location. The document at the referenced location may or may not exist. + +Signature: + +```typescript +export declare class DocumentReference +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [converter](./firestore_lite.documentreference.md#documentreferenceconverter) | | [FirestoreDataConverter](./firestore_lite.firestoredataconverter.md#firestoredataconverter_interface)<T> \| null | If provided, the FirestoreDataConverter associated with this instance. | +| [firestore](./firestore_lite.documentreference.md#documentreferencefirestore) | | [Firestore](./firestore_lite.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance the document is in. This is useful for performing transactions, for example. | +| [id](./firestore_lite.documentreference.md#documentreferenceid) | | string | The document's identifier within its collection. | +| [parent](./firestore_lite.documentreference.md#documentreferenceparent) | | [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | The collection this DocumentReference belongs to. | +| [path](./firestore_lite.documentreference.md#documentreferencepath) | | string | A string representing the path of the referenced document (relative to the root of the database). | +| [type](./firestore_lite.documentreference.md#documentreferencetype) | | (not declared) | The type of this Firestore reference. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [withConverter(converter)](./firestore_lite.documentreference.md#documentreferencewithconverter) | | Applies a custom data converter to this DocumentReference, allowing you to use your own custom model objects with Firestore. When you call [setDoc()](./firestore_lite.md#setdoc), [getDoc()](./firestore_lite.md#getdoc), etc. with the returned DocumentReference instance, the provided converter will convert between Firestore data and your custom type U. | +| [withConverter(converter)](./firestore_lite.documentreference.md#documentreferencewithconverter) | | Removes the current converter. | + +## DocumentReference.converter + +If provided, the `FirestoreDataConverter` associated with this instance. + +Signature: + +```typescript +readonly converter: FirestoreDataConverter | null; +``` + +## DocumentReference.firestore + +The [Firestore](./firestore_.firestore.md#firestore_class) instance the document is in. This is useful for performing transactions, for example. + +Signature: + +```typescript +readonly firestore: Firestore; +``` + +## DocumentReference.id + +The document's identifier within its collection. + +Signature: + +```typescript +get id(): string; +``` + +## DocumentReference.parent + +The collection this `DocumentReference` belongs to. + +Signature: + +```typescript +get parent(): CollectionReference; +``` + +## DocumentReference.path + +A string representing the path of the referenced document (relative to the root of the database). + +Signature: + +```typescript +get path(): string; +``` + +## DocumentReference.type + +The type of this Firestore reference. + +Signature: + +```typescript +readonly type = "document"; +``` + +## DocumentReference.withConverter() + +Applies a custom data converter to this `DocumentReference`, allowing you to use your own custom model objects with Firestore. When you call [setDoc()](./firestore_lite.md#setdoc), [getDoc()](./firestore_lite.md#getdoc), etc. with the returned `DocumentReference` instance, the provided converter will convert between Firestore data and your custom type `U`. + +Signature: + +```typescript +withConverter(converter: FirestoreDataConverter): DocumentReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| converter | [FirestoreDataConverter](./firestore_lite.firestoredataconverter.md#firestoredataconverter_interface)<U> | Converts objects to and from Firestore. | + +Returns: + +[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<U> + +A `DocumentReference` that uses the provided converter. + +## DocumentReference.withConverter() + +Removes the current converter. + +Signature: + +```typescript +withConverter(converter: null): DocumentReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| converter | null | null removes the current converter. | + +Returns: + +[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> + +A `DocumentReference` that does not use a converter. + diff --git a/docs-devsite/firestore_lite.documentsnapshot.md b/docs-devsite/firestore_lite.documentsnapshot.md new file mode 100644 index 00000000000..cfea1feb919 --- /dev/null +++ b/docs-devsite/firestore_lite.documentsnapshot.md @@ -0,0 +1,125 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# DocumentSnapshot class +A `DocumentSnapshot` contains data read from a document in your Firestore database. The data can be extracted with `.data()` or `.get()` to get a specific field. + +For a `DocumentSnapshot` that points to a non-existing document, any data access will return 'undefined'. You can use the `exists()` method to explicitly verify a document's existence. + +Signature: + +```typescript +export declare class DocumentSnapshot +``` + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)()](./firestore_lite.documentsnapshot.md#documentsnapshotconstructor) | | Constructs a new instance of the DocumentSnapshot class | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [id](./firestore_lite.documentsnapshot.md#documentsnapshotid) | | string | Property of the DocumentSnapshot that provides the document's ID. | +| [ref](./firestore_lite.documentsnapshot.md#documentsnapshotref) | | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | The DocumentReference for the document included in the DocumentSnapshot. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [data()](./firestore_lite.documentsnapshot.md#documentsnapshotdata) | | Retrieves all fields in the document as an Object. Returns undefined if the document doesn't exist. | +| [exists()](./firestore_lite.documentsnapshot.md#documentsnapshotexists) | | Signals whether or not the document at the snapshot's location exists. | +| [get(fieldPath)](./firestore_lite.documentsnapshot.md#documentsnapshotget) | | Retrieves the field specified by fieldPath. Returns undefined if the document or field doesn't exist. | + +## DocumentSnapshot.(constructor) + +Constructs a new instance of the `DocumentSnapshot` class + +Signature: + +```typescript +protected constructor(); +``` + +## DocumentSnapshot.id + +Property of the `DocumentSnapshot` that provides the document's ID. + +Signature: + +```typescript +get id(): string; +``` + +## DocumentSnapshot.ref + +The `DocumentReference` for the document included in the `DocumentSnapshot`. + +Signature: + +```typescript +get ref(): DocumentReference; +``` + +## DocumentSnapshot.data() + +Retrieves all fields in the document as an `Object`. Returns `undefined` if the document doesn't exist. + +Signature: + +```typescript +data(): T | undefined; +``` +Returns: + +T \| undefined + +An `Object` containing all fields in the document or `undefined` if the document doesn't exist. + +## DocumentSnapshot.exists() + +Signals whether or not the document at the snapshot's location exists. + +Signature: + +```typescript +exists(): this is QueryDocumentSnapshot; +``` +Returns: + +this is [QueryDocumentSnapshot](./firestore_lite.querydocumentsnapshot.md#querydocumentsnapshot_class)<T> + +true if the document exists. + +## DocumentSnapshot.get() + +Retrieves the field specified by `fieldPath`. Returns `undefined` if the document or field doesn't exist. + +Signature: + +```typescript +get(fieldPath: string | FieldPath): any; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldPath | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The path (for example 'foo' or 'foo.bar') to a specific field. | + +Returns: + +any + +The data at the specified field location or undefined if no such field exists in the document. + diff --git a/docs-devsite/firestore_lite.fieldpath.md b/docs-devsite/firestore_lite.fieldpath.md new file mode 100644 index 00000000000..ea449fc065b --- /dev/null +++ b/docs-devsite/firestore_lite.fieldpath.md @@ -0,0 +1,72 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FieldPath class +A `FieldPath` refers to a field in a document. The path may consist of a single field name (referring to a top-level field in the document), or a list of field names (referring to a nested field in the document). + +Create a `FieldPath` by providing field names. If more than one field name is provided, the path will point to a nested field in a document. + +Signature: + +```typescript +export declare class FieldPath +``` + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(fieldNames)](./firestore_lite.fieldpath.md#fieldpathconstructor) | | Creates a FieldPath from the provided field names. If more than one field name is provided, the path will point to a nested field in a document. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [isEqual(other)](./firestore_lite.fieldpath.md#fieldpathisequal) | | Returns true if this FieldPath is equal to the provided one. | + +## FieldPath.(constructor) + +Creates a `FieldPath` from the provided field names. If more than one field name is provided, the path will point to a nested field in a document. + +Signature: + +```typescript +constructor(...fieldNames: string[]); +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldNames | string\[\] | A list of field names. | + +## FieldPath.isEqual() + +Returns true if this `FieldPath` is equal to the provided one. + +Signature: + +```typescript +isEqual(other: FieldPath): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| other | [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The FieldPath to compare against. | + +Returns: + +boolean + +true if this `FieldPath` is equal to the provided one. + diff --git a/docs-devsite/firestore_lite.fieldvalue.md b/docs-devsite/firestore_lite.fieldvalue.md new file mode 100644 index 00000000000..454693c9771 --- /dev/null +++ b/docs-devsite/firestore_lite.fieldvalue.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FieldValue class +Sentinel values that can be used when writing document fields with `set()` or `update()`. + +Signature: + +```typescript +export declare abstract class FieldValue +``` + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [isEqual(other)](./firestore_lite.fieldvalue.md#fieldvalueisequal) | | Compares FieldValues for equality. | + +## FieldValue.isEqual() + +Compares `FieldValue`s for equality. + +Signature: + +```typescript +abstract isEqual(other: FieldValue): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| other | [FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) | | + +Returns: + +boolean + diff --git a/docs-devsite/firestore_lite.firestore.md b/docs-devsite/firestore_lite.firestore.md new file mode 100644 index 00000000000..2edac7aa130 --- /dev/null +++ b/docs-devsite/firestore_lite.firestore.md @@ -0,0 +1,68 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Firestore class +The Cloud Firestore service interface. + +Do not call this constructor directly. Instead, use [getFirestore()](./firestore_.md#getfirestore). + +Signature: + +```typescript +export declare class Firestore +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [app](./firestore_lite.firestore.md#firestoreapp) | | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this Firestore service instance. | +| [type](./firestore_lite.firestore.md#firestoretype) | | 'firestore-lite' \| 'firestore' | Whether it's a Firestore or Firestore Lite instance. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [toJSON()](./firestore_lite.firestore.md#firestoretojson) | | Returns a JSON-serializable representation of this Firestore instance. | + +## Firestore.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this `Firestore` service instance. + +Signature: + +```typescript +get app(): FirebaseApp; +``` + +## Firestore.type + +Whether it's a Firestore or Firestore Lite instance. + +Signature: + +```typescript +type: 'firestore-lite' | 'firestore'; +``` + +## Firestore.toJSON() + +Returns a JSON-serializable representation of this `Firestore` instance. + +Signature: + +```typescript +toJSON(): object; +``` +Returns: + +object + diff --git a/docs-devsite/firestore_lite.firestoredataconverter.md b/docs-devsite/firestore_lite.firestoredataconverter.md new file mode 100644 index 00000000000..00510e0c22b --- /dev/null +++ b/docs-devsite/firestore_lite.firestoredataconverter.md @@ -0,0 +1,130 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FirestoreDataConverter interface +Converter used by `withConverter()` to transform user objects of type `T` into Firestore data. + +Using the converter allows you to specify generic type arguments when storing and retrieving objects from Firestore. + +Signature: + +```typescript +export declare interface FirestoreDataConverter +``` + +## Methods + +| Method | Description | +| --- | --- | +| [fromFirestore(snapshot)](./firestore_lite.firestoredataconverter.md#firestoredataconverterfromfirestore) | Called by the Firestore SDK to convert Firestore data into an object of type T. You can access your data by calling: snapshot.data(). | +| [toFirestore(modelObject)](./firestore_lite.firestoredataconverter.md#firestoredataconvertertofirestore) | Called by the Firestore SDK to convert a custom model object of type T into a plain Javascript object (suitable for writing directly to the Firestore database). Used with [setDoc()](./firestore_lite.md#setdoc), and .The WithFieldValue<T> type extends T to also allow FieldValues such as [deleteField()](./firestore_.md#deletefield) to be used as property values. | +| [toFirestore(modelObject, options)](./firestore_lite.firestoredataconverter.md#firestoredataconvertertofirestore) | Called by the Firestore SDK to convert a custom model object of type T into a plain Javascript object (suitable for writing directly to the Firestore database). Used with [setDoc()](./firestore_lite.md#setdoc), and with merge:true or mergeFields.The PartialWithFieldValue<T> type extends Partial<T> to allow FieldValues such as [arrayUnion()](./firestore_.md#arrayunion) to be used as property values. It also supports nested Partial by allowing nested fields to be omitted. | + +## FirestoreDataConverter.fromFirestore() + +Called by the Firestore SDK to convert Firestore data into an object of type T. You can access your data by calling: `snapshot.data()`. + +Signature: + +```typescript +fromFirestore(snapshot: QueryDocumentSnapshot): T; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| snapshot | [QueryDocumentSnapshot](./firestore_lite.querydocumentsnapshot.md#querydocumentsnapshot_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> | A QueryDocumentSnapshot containing your data and metadata. | + +Returns: + +T + +## FirestoreDataConverter.toFirestore() + +Called by the Firestore SDK to convert a custom model object of type `T` into a plain Javascript object (suitable for writing directly to the Firestore database). Used with [setDoc()](./firestore_lite.md#setdoc), and . + +The `WithFieldValue` type extends `T` to also allow FieldValues such as [deleteField()](./firestore_.md#deletefield) to be used as property values. + +Signature: + +```typescript +toFirestore(modelObject: WithFieldValue): DocumentData; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| modelObject | [WithFieldValue](./firestore_lite.md#withfieldvalue)<T> | | + +Returns: + +[DocumentData](./firestore_lite.documentdata.md#documentdata_interface) + +## FirestoreDataConverter.toFirestore() + +Called by the Firestore SDK to convert a custom model object of type `T` into a plain Javascript object (suitable for writing directly to the Firestore database). Used with [setDoc()](./firestore_lite.md#setdoc), and with `merge:true` or `mergeFields`. + +The `PartialWithFieldValue` type extends `Partial` to allow FieldValues such as [arrayUnion()](./firestore_.md#arrayunion) to be used as property values. It also supports nested `Partial` by allowing nested fields to be omitted. + +Signature: + +```typescript +toFirestore(modelObject: PartialWithFieldValue, options: SetOptions): DocumentData; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| modelObject | [PartialWithFieldValue](./firestore_lite.md#partialwithfieldvalue)<T> | | +| options | [SetOptions](./firestore_lite.md#setoptions) | | + +Returns: + +[DocumentData](./firestore_lite.documentdata.md#documentdata_interface) + +### Example + + +```typescript +class Post { + constructor(readonly title: string, readonly author: string) {} + + toString(): string { + return this.title + ', by ' + this.author; + } +} + +const postConverter = { + toFirestore(post: WithFieldValue): DocumentData { + return {title: post.title, author: post.author}; + }, + fromFirestore(snapshot: QueryDocumentSnapshot): Post { + const data = snapshot.data(options)!; + return new Post(data.title, data.author); + } +}; + +const postSnap = await firebase.firestore() + .collection('posts') + .withConverter(postConverter) + .doc().get(); +const post = postSnap.data(); +if (post !== undefined) { + post.title; // string + post.toString(); // Should be defined + post.someNonExistentProperty; // TS error +} + +``` + diff --git a/docs-devsite/firestore_lite.firestoreerror.md b/docs-devsite/firestore_lite.firestoreerror.md new file mode 100644 index 00000000000..e3c6dd23029 --- /dev/null +++ b/docs-devsite/firestore_lite.firestoreerror.md @@ -0,0 +1,58 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FirestoreError class +An error returned by a Firestore operation. + +Signature: + +```typescript +export declare class FirestoreError extends FirebaseError +``` +Extends: [FirebaseError](./util.firebaseerror.md#firebaseerror_class) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [code](./firestore_lite.firestoreerror.md#firestoreerrorcode) | | [FirestoreErrorCode](./firestore_lite.md#firestoreerrorcode) | The backend error code associated with this error. | +| [message](./firestore_lite.firestoreerror.md#firestoreerrormessage) | | string | A custom error description. | +| [stack](./firestore_lite.firestoreerror.md#firestoreerrorstack) | | string | The stack of the error. | + +## FirestoreError.code + +The backend error code associated with this error. + +Signature: + +```typescript +readonly code: FirestoreErrorCode; +``` + +## FirestoreError.message + +A custom error description. + +Signature: + +```typescript +readonly message: string; +``` + +## FirestoreError.stack + +The stack of the error. + +Signature: + +```typescript +readonly stack?: string; +``` diff --git a/docs-devsite/firestore_lite.geopoint.md b/docs-devsite/firestore_lite.geopoint.md new file mode 100644 index 00000000000..23576c41d8d --- /dev/null +++ b/docs-devsite/firestore_lite.geopoint.md @@ -0,0 +1,117 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# GeoPoint class +An immutable object representing a geographic location in Firestore. The location is represented as latitude/longitude pair. + +Latitude values are in the range of \[-90, 90\]. Longitude values are in the range of \[-180, 180\]. + +Signature: + +```typescript +export declare class GeoPoint +``` + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(latitude, longitude)](./firestore_lite.geopoint.md#geopointconstructor) | | Creates a new immutable GeoPoint object with the provided latitude and longitude values. | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [latitude](./firestore_lite.geopoint.md#geopointlatitude) | | number | The latitude of this GeoPoint instance. | +| [longitude](./firestore_lite.geopoint.md#geopointlongitude) | | number | The longitude of this GeoPoint instance. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [isEqual(other)](./firestore_lite.geopoint.md#geopointisequal) | | Returns true if this GeoPoint is equal to the provided one. | +| [toJSON()](./firestore_lite.geopoint.md#geopointtojson) | | Returns a JSON-serializable representation of this GeoPoint. | + +## GeoPoint.(constructor) + +Creates a new immutable `GeoPoint` object with the provided latitude and longitude values. + +Signature: + +```typescript +constructor(latitude: number, longitude: number); +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| latitude | number | The latitude as number between -90 and 90. | +| longitude | number | The longitude as number between -180 and 180. | + +## GeoPoint.latitude + +The latitude of this `GeoPoint` instance. + +Signature: + +```typescript +get latitude(): number; +``` + +## GeoPoint.longitude + +The longitude of this `GeoPoint` instance. + +Signature: + +```typescript +get longitude(): number; +``` + +## GeoPoint.isEqual() + +Returns true if this `GeoPoint` is equal to the provided one. + +Signature: + +```typescript +isEqual(other: GeoPoint): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| other | [GeoPoint](./firestore_lite.geopoint.md#geopoint_class) | The GeoPoint to compare against. | + +Returns: + +boolean + +true if this `GeoPoint` is equal to the provided one. + +## GeoPoint.toJSON() + +Returns a JSON-serializable representation of this GeoPoint. + +Signature: + +```typescript +toJSON(): { + latitude: number; + longitude: number; + }; +``` +Returns: + +{ latitude: number; longitude: number; } + diff --git a/docs-devsite/firestore_lite.md b/docs-devsite/firestore_lite.md new file mode 100644 index 00000000000..3754cda22b7 --- /dev/null +++ b/docs-devsite/firestore_lite.md @@ -0,0 +1,1443 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# @firebase/firestore/lite + +## Functions + +| Function | Description | +| --- | --- | +| function(app...) | +| [getFirestore(app)](./firestore_lite.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. | +| [initializeFirestore(app, settings)](./firestore_lite.md#initializefirestore) | Initializes a new instance of Cloud Firestore with the provided settings. Can only be called before any other functions, including [getFirestore()](./firestore_.md#getfirestore). If the custom settings are empty, this function is equivalent to calling [getFirestore()](./firestore_.md#getfirestore). | +| function(firestore...) | +| [collection(firestore, path, pathSegments)](./firestore_lite.md#collection) | Gets a CollectionReference instance that refers to the collection at the specified absolute path. | +| [collectionGroup(firestore, collectionId)](./firestore_lite.md#collectiongroup) | Creates and returns a new Query instance that includes all documents in the database that are contained in a collection or subcollection with the given collectionId. | +| [connectFirestoreEmulator(firestore, host, port, options)](./firestore_lite.md#connectfirestoreemulator) | Modify this instance to communicate with the Cloud Firestore emulator.Note: This must be called before this instance has been used to do any operations. | +| [doc(firestore, path, pathSegments)](./firestore_lite.md#doc) | Gets a DocumentReference instance that refers to the document at the specified absolute path. | +| [runTransaction(firestore, updateFunction, options)](./firestore_lite.md#runtransaction) | Executes the given updateFunction and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, Cloud Firestore retries the updateFunction. If it fails to commit after 5 attempts, the transaction fails.The maximum number of writes allowed in a single transaction is 500. | +| [terminate(firestore)](./firestore_lite.md#terminate) | Terminates the provided Firestore instance.After calling terminate() only the clearIndexedDbPersistence() functions may be used. Any other function will throw a FirestoreError. Termination does not cancel any pending writes, and any promises that are awaiting a response from the server will not be resolved.To restart after termination, create a new instance of Firestore with [getFirestore()](./firestore_.md#getfirestore).Note: Under normal circumstances, calling terminate() is not required. This function is useful only when you want to force this instance to release all of its resources or in combination with [clearIndexedDbPersistence()](./firestore_.md#clearindexeddbpersistence) to ensure that all local state is destroyed between test runs. | +| [writeBatch(firestore)](./firestore_lite.md#writebatch) | Creates a write batch, used for performing multiple writes as a single atomic operation. The maximum number of writes allowed in a single WriteBatch is 500.The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | +| function() | +| [deleteField()](./firestore_lite.md#deletefield) | Returns a sentinel for use with [updateDoc()](./firestore_lite.md#updatedoc) or [setDoc()](./firestore_lite.md#setdoc) with {merge: true} to mark a field for deletion. | +| [documentId()](./firestore_lite.md#documentid) | Returns a special sentinel FieldPath to refer to the ID of a document. It can be used in queries to sort or filter by the document ID. | +| [getFirestore()](./firestore_lite.md#getfirestore) | Returns the existing default [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. | +| [serverTimestamp()](./firestore_lite.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(elements...) | +| [arrayRemove(elements)](./firestore_lite.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_lite.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. | +| function(fieldPath...) | +| [orderBy(fieldPath, directionStr)](./firestore_lite.md#orderby) | Creates a [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class) that sorts the query result by the specified field, optionally in descending order instead of ascending.Note: Documents that do not contain the specified field will not be present in the query result. | +| [where(fieldPath, opStr, value)](./firestore_lite.md#where) | Creates a [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) that enforces that documents must contain the specified field and that the value should satisfy the relation constraint provided. | +| function(fieldValues...) | +| [endAt(fieldValues)](./firestore_lite.md#endat) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | +| [endBefore(fieldValues)](./firestore_lite.md#endbefore) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | +| [startAfter(fieldValues)](./firestore_lite.md#startafter) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | +| [startAt(fieldValues)](./firestore_lite.md#startat) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | +| function(left...) | +| [aggregateQuerySnapshotEqual(left, right)](./firestore_lite.md#aggregatequerysnapshotequal) | Compares two AggregateQuerySnapshot instances for equality.Two AggregateQuerySnapshot instances are considered "equal" if they have underlying queries that compare equal, and the same data. | +| [queryEqual(left, right)](./firestore_lite.md#queryequal) | Returns true if the provided queries point to the same collection and apply the same constraints. | +| [refEqual(left, right)](./firestore_lite.md#refequal) | Returns true if the provided references are equal. | +| [snapshotEqual(left, right)](./firestore_lite.md#snapshotequal) | Returns true if the provided snapshots are equal. | +| function(limit...) | +| [limit(limit)](./firestore_lite.md#limit) | Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the first matching documents. | +| [limitToLast(limit)](./firestore_lite.md#limittolast) | Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the last matching documents.You must specify at least one orderBy clause for limitToLast queries, otherwise an exception will be thrown during execution. | +| function(logLevel...) | +| [setLogLevel(logLevel)](./firestore_lite.md#setloglevel) | Sets the verbosity of Cloud Firestore logs (debug, error, or silent). | +| function(n...) | +| [increment(n)](./firestore_lite.md#increment) | 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 increment the field's current value by the given value.If either the operand or the current field value uses floating point precision, all arithmetic follows IEEE 754 semantics. If both values are integers, values outside of JavaScript's safe number range (Number.MIN_SAFE_INTEGER to Number.MAX_SAFE_INTEGER) are also subject to precision loss. Furthermore, once processed by the Firestore backend, all integer operations are capped between -2^63 and 2^63-1.If the current field value is not of type number, or if the field does not yet exist, the transformation sets the field to the given value. | +| function(query...) | +| [getCount(query)](./firestore_lite.md#getcount) | Calculates the number of documents in the result set of the given query, without actually downloading the documents.Using this function to count the documents is efficient because only the final count, not the documents' data, is downloaded. This function can even count the documents if the result set would be prohibitively large to download entirely (e.g. thousands of documents). | +| [getDocs(query)](./firestore_lite.md#getdocs) | Executes the query and returns the results as a [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class).All queries are executed directly by the server, even if the the query was previously executed. Recent modifications are only reflected in the retrieved results if they have already been applied by the backend. If the client is offline, the operation fails. To see previously cached result and local modifications, use the full Firestore SDK. | +| [query(query, queryConstraints)](./firestore_lite.md#query) | Creates a new immutable instance of [Query](./firestore_.query.md#query_class) that is extended to also include additional query constraints. | +| function(reference...) | +| [addDoc(reference, data)](./firestore_lite.md#adddoc) | Add a new document to specified CollectionReference with the given data, assigning it a document ID automatically.The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | +| [collection(reference, path, pathSegments)](./firestore_lite.md#collection) | Gets a CollectionReference instance that refers to a subcollection of reference at the the specified relative path. | +| [collection(reference, path, pathSegments)](./firestore_lite.md#collection) | Gets a CollectionReference instance that refers to a subcollection of reference at the the specified relative path. | +| [deleteDoc(reference)](./firestore_lite.md#deletedoc) | Deletes the document referred to by the specified DocumentReference.The deletion will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the delete fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | +| [doc(reference, path, pathSegments)](./firestore_lite.md#doc) | Gets a DocumentReference instance that refers to a document within reference at the specified relative path. If no path is specified, an automatically-generated unique ID will be used for the returned DocumentReference. | +| [doc(reference, path, pathSegments)](./firestore_lite.md#doc) | Gets a DocumentReference instance that refers to a document within reference at the specified relative path. | +| [getDoc(reference)](./firestore_lite.md#getdoc) | Reads the document referred to by the specified document reference.All documents are directly fetched from the server, even if the document was previously read or modified. Recent modifications are only reflected in the retrieved DocumentSnapshot if they have already been applied by the backend. If the client is offline, the read fails. If you like to use caching or see local modifications, please use the full Firestore SDK. | +| [setDoc(reference, data)](./firestore_lite.md#setdoc) | Writes to the document referred to by the specified DocumentReference. If the document does not yet exist, it will be created.The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | +| [setDoc(reference, data, options)](./firestore_lite.md#setdoc) | Writes to the document referred to by the specified DocumentReference. If the document does not yet exist, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document.The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | +| [updateDoc(reference, data)](./firestore_lite.md#updatedoc) | Updates fields in the document referred to by the specified DocumentReference. The update will fail if applied to a document that does not exist.The result of this update will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the update fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | +| [updateDoc(reference, field, value, moreFieldsAndValues)](./firestore_lite.md#updatedoc) | Updates fields in the document referred to by the specified DocumentReference The update will fail if applied to a document that does not exist.Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects.The result of this update will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the update fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | +| function(snapshot...) | +| [endAt(snapshot)](./firestore_lite.md#endat) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided document (inclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | +| [endBefore(snapshot)](./firestore_lite.md#endbefore) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | +| [startAfter(snapshot)](./firestore_lite.md#startafter) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | +| [startAt(snapshot)](./firestore_lite.md#startat) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of this query. | + +## Classes + +| Class | Description | +| --- | --- | +| [AggregateField](./firestore_lite.aggregatefield.md#aggregatefield_class) | Represents an aggregation that can be performed by Firestore. | +| [AggregateQuerySnapshot](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshot_class) | The results of executing an aggregation query. | +| [Bytes](./firestore_lite.bytes.md#bytes_class) | An immutable object representing an array of bytes. | +| [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class) | A CollectionReference object can be used for adding documents, getting document references, and querying for documents (using [query()](./firestore_.md#query)). | +| [DocumentReference](./firestore_lite.documentreference.md#documentreference_class) | A DocumentReference refers to a document location in a Firestore database and can be used to write, read, or listen to the location. The document at the referenced location may or may not exist. | +| [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class) | A DocumentSnapshot contains data read from a document in your Firestore database. The data can be extracted with .data() or .get(<field>) to get a specific field.For a DocumentSnapshot that points to a non-existing document, any data access will return 'undefined'. You can use the exists() method to explicitly verify a document's existence. | +| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | A FieldPath refers to a field in a document. The path may consist of a single field name (referring to a top-level field in the document), or a list of field names (referring to a nested field in the document).Create a FieldPath by providing field names. If more than one field name is provided, the path will point to a nested field in a document. | +| [FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) | Sentinel values that can be used when writing document fields with set() or update(). | +| [Firestore](./firestore_lite.firestore.md#firestore_class) | The Cloud Firestore service interface.Do not call this constructor directly. Instead, use [getFirestore()](./firestore_.md#getfirestore). | +| [FirestoreError](./firestore_lite.firestoreerror.md#firestoreerror_class) | An error returned by a Firestore operation. | +| [GeoPoint](./firestore_lite.geopoint.md#geopoint_class) | An immutable object representing a geographic location in Firestore. The location is represented as latitude/longitude pair.Latitude values are in the range of \[-90, 90\]. Longitude values are in the range of \[-180, 180\]. | +| [Query](./firestore_lite.query.md#query_class) | A Query refers to a query which you can read or listen to. You can also construct refined Query objects by adding filters and ordering. | +| [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) | A QueryConstraint is used to narrow the set of documents returned by a Firestore query. QueryConstraints are created by invoking [where()](./firestore_.md#where), [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit), [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryConstraint. | +| [QueryDocumentSnapshot](./firestore_lite.querydocumentsnapshot.md#querydocumentsnapshot_class) | A QueryDocumentSnapshot contains data read from a document in your Firestore database as part of a query. The document is guaranteed to exist and its data can be extracted with .data() or .get(<field>) to get a specific field.A QueryDocumentSnapshot offers the same API surface as a DocumentSnapshot. Since query results contain only existing documents, the exists property will always be true and data() will never return 'undefined'. | +| [QueryEndAtConstraint](./firestore_lite.queryendatconstraint.md#queryendatconstraint_class) | A QueryEndAtConstraint is used to exclude documents from the end of a result set returned by a Firestore query. QueryEndAtConstraints are created by invoking [endAt()](./firestore_.md#endat) or [endBefore()](./firestore_.md#endbefore) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryEndAtConstraint. | +| [QueryFieldFilterConstraint](./firestore_lite.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) | A QueryFieldFilterConstraint is used to narrow the set of documents returned by a Firestore query by filtering on one or more document fields. QueryFieldFilterConstraints are created by invoking [where()](./firestore_.md#where) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryFieldFilterConstraint. | +| [QueryLimitConstraint](./firestore_lite.querylimitconstraint.md#querylimitconstraint_class) | A QueryLimitConstraint is used to limit the number of documents returned by a Firestore query. QueryLimitConstraints are created by invoking [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryLimitConstraint. | +| [QueryOrderByConstraint](./firestore_lite.queryorderbyconstraint.md#queryorderbyconstraint_class) | A QueryOrderByConstraint is used to sort the set of documents returned by a Firestore query. QueryOrderByConstraints are created by invoking [orderBy()](./firestore_.md#orderby) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryOrderByConstraint.Note: Documents that do not contain the orderBy field will not be present in the query result. | +| [QuerySnapshot](./firestore_lite.querysnapshot.md#querysnapshot_class) | A QuerySnapshot contains zero or more DocumentSnapshot objects representing the results of a query. The documents can be accessed as an array via the docs property or enumerated using the forEach method. The number of documents can be determined via the empty and size properties. | +| [QueryStartAtConstraint](./firestore_lite.querystartatconstraint.md#querystartatconstraint_class) | A QueryStartAtConstraint is used to exclude documents from the start of a result set returned by a Firestore query. QueryStartAtConstraints are created by invoking [startAt()](./firestore_.md#startat) or [startAfter()](./firestore_.md#startafter) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryStartAtConstraint. | +| [Timestamp](./firestore_lite.timestamp.md#timestamp_class) | A Timestamp represents a point in time independent of any time zone or calendar, represented as seconds and fractions of seconds at nanosecond resolution in UTC Epoch time.It is encoded using the Proleptic Gregorian Calendar which extends the Gregorian calendar backwards to year one. It is encoded assuming all minutes are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.For examples and further specifications, refer to the [Timestamp definition](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto). | +| [Transaction](./firestore_lite.transaction.md#transaction_class) | A reference to a transaction.The Transaction object passed to a transaction's updateFunction provides the methods to read and write data within the transaction context. See [runTransaction()](./firestore_.md#runtransaction). | +| [WriteBatch](./firestore_lite.writebatch.md#writebatch_class) | A write batch, used to perform multiple writes as a single atomic unit.A WriteBatch object can be acquired by calling [writeBatch()](./firestore_.md#writebatch). It provides methods for adding writes to the write batch. None of the writes will be committed (or visible locally) until [WriteBatch.commit()](./firestore_.writebatch.md#writebatchcommit) is called. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [AggregateSpec](./firestore_lite.aggregatespec.md#aggregatespec_interface) | A type whose property values are all AggregateField objects. | +| [DocumentData](./firestore_lite.documentdata.md#documentdata_interface) | Document data (for use with [setDoc()](./firestore_lite.md#setdoc)) consists of fields mapped to values. | +| [FirestoreDataConverter](./firestore_lite.firestoredataconverter.md#firestoredataconverter_interface) | Converter used by withConverter() to transform user objects of type T into Firestore data.Using the converter allows you to specify generic type arguments when storing and retrieving objects from Firestore. | +| [Settings](./firestore_lite.settings.md#settings_interface) | Specifies custom configurations for your Cloud Firestore instance. You must set these before invoking any other methods. | +| [TransactionOptions](./firestore_lite.transactionoptions.md#transactionoptions_interface) | Options to customize transaction behavior. | + +## Type Aliases + +| Type Alias | Description | +| --- | --- | +| [AddPrefixToKeys](./firestore_lite.md#addprefixtokeys) | Returns a new map where every key is prefixed with the outer key appended to a dot. | +| [AggregateFieldType](./firestore_lite.md#aggregatefieldtype) | The union of all AggregateField types that are supported by Firestore. | +| [AggregateSpecData](./firestore_lite.md#aggregatespecdata) | A type whose keys are taken from an AggregateSpec, and whose values are the result of the aggregation performed by the corresponding AggregateField from the input AggregateSpec. | +| [ChildUpdateFields](./firestore_lite.md#childupdatefields) | Helper for calculating the nested fields for a given type T1. This is needed to distribute union types such as undefined | {...} (happens for optional props) or {a: A} | {b: B}.In this use case, V is used to distribute the union types of T[K] on Record, since T[K] is evaluated as an expression and not distributed.See https://www.typescriptlang.org/docs/handbook/advanced-types.html\#distributive-conditional-types | +| [FirestoreErrorCode](./firestore_lite.md#firestoreerrorcode) | The set of Firestore status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.mdPossible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (e.g. an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation. | +| [NestedUpdateFields](./firestore_lite.md#nestedupdatefields) | For each field (e.g. 'bar'), find all nested keys (e.g. {'bar.baz': T1, 'bar.qux': T2}). Intersect them together to make a single map containing all possible keys that are all marked as optional | +| [OrderByDirection](./firestore_lite.md#orderbydirection) | The direction of a [orderBy()](./firestore_.md#orderby) clause is specified as 'desc' or 'asc' (descending or ascending). | +| [PartialWithFieldValue](./firestore_lite.md#partialwithfieldvalue) | Similar to Typescript's Partial<T>, but allows nested fields to be omitted and FieldValues to be passed in as property values. | +| [Primitive](./firestore_lite.md#primitive) | Primitive types. | +| [QueryConstraintType](./firestore_lite.md#queryconstrainttype) | Describes the different query constraints available in this SDK. | +| [QueryNonFilterConstraint](./firestore_lite.md#querynonfilterconstraint) | QueryNonFilterConstraint is a helper union type that represents QueryConstraints which are used to narrow or order the set of documents, but that do not explicitly filter on a document field. QueryNonFilterConstraints are created by invoking [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains the QueryConstraint. | +| [SetOptions](./firestore_lite.md#setoptions) | An options object that configures the behavior of [setDoc()](./firestore_lite.md#setdoc), and calls. These calls can be configured to perform granular merges instead of overwriting the target documents in their entirety by providing a SetOptions with merge: true. | +| [UnionToIntersection](./firestore_lite.md#uniontointersection) | Given a union type U = T1 | T2 | ..., returns an intersected type (T1 & T2 & ...).Uses distributive conditional types and inference from conditional types. This works because multiple candidates for the same type variable in contra-variant positions causes an intersection type to be inferred. https://www.typescriptlang.org/docs/handbook/advanced-types.html\#type-inference-in-conditional-types https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection-type | +| [UpdateData](./firestore_lite.md#updatedata) | Update data (for use with [updateDoc()](./firestore_.md#updatedoc)) that consists of field paths (e.g. 'foo' or 'foo.baz') mapped to values. Fields that contain dots reference nested fields within the document. FieldValues can be passed in as property values. | +| [WhereFilterOp](./firestore_lite.md#wherefilterop) | Filter conditions in a [where()](./firestore_.md#where) clause are specified using the strings '&lt;', '&lt;=', '==', '!=', '&gt;=', '&gt;', 'array-contains', 'in', 'array-contains-any', and 'not-in'. | +| [WithFieldValue](./firestore_lite.md#withfieldvalue) | Allows FieldValues to be passed in as a property value while maintaining type safety. | + +## 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. + +Signature: + +```typescript +export declare function getFirestore(app: FirebaseApp): Firestore; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance that the returned [Firestore](./firestore_.firestore.md#firestore_class) instance is associated with. | + +Returns: + +[Firestore](./firestore_lite.firestore.md#firestore_class) + +The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. + +## initializeFirestore() + +Initializes a new instance of Cloud Firestore with the provided settings. Can only be called before any other functions, including [getFirestore()](./firestore_.md#getfirestore). If the custom settings are empty, this function is equivalent to calling [getFirestore()](./firestore_.md#getfirestore). + +Signature: + +```typescript +export declare function initializeFirestore(app: FirebaseApp, settings: Settings): Firestore; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) with which the Firestore instance will be associated. | +| settings | [Settings](./firestore_lite.settings.md#settings_interface) | A settings object to configure the Firestore instance. | + +Returns: + +[Firestore](./firestore_lite.firestore.md#firestore_class) + +A newly initialized `Firestore` instance. + +## collection() + +Gets a `CollectionReference` instance that refers to the collection at the specified absolute path. + +Signature: + +```typescript +export declare function collection(firestore: Firestore, path: string, ...pathSegments: string[]): CollectionReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | A reference to the root Firestore instance. | +| path | string | A slash-separated path to a collection. | +| pathSegments | string\[\] | Additional path segments to apply relative to the first argument. | + +Returns: + +[CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> + +The `CollectionReference` instance. + +## Exceptions + +If the final path has an even number of segments and does not point to a collection. + +## collectionGroup() + +Creates and returns a new `Query` instance that includes all documents in the database that are contained in a collection or subcollection with the given `collectionId`. + +Signature: + +```typescript +export declare function collectionGroup(firestore: Firestore, collectionId: string): Query; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | A reference to the root Firestore instance. | +| collectionId | string | Identifies the collections to query over. Every collection or subcollection with this ID as the last segment of its path will be included. Cannot contain a slash. | + +Returns: + +[Query](./firestore_lite.query.md#query_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> + +The created `Query`. + +## connectFirestoreEmulator() + +Modify this instance to communicate with the Cloud Firestore emulator. + +Note: This must be called before this instance has been used to do any operations. + +Signature: + +```typescript +export declare function connectFirestoreEmulator(firestore: Firestore, host: string, port: number, options?: { + mockUserToken?: EmulatorMockTokenOptions | string; +}): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | The Firestore instance to configure to connect to the emulator. | +| host | string | the emulator host (ex: localhost). | +| port | number | the emulator port (ex: 9000). | +| options | { mockUserToken?: [EmulatorMockTokenOptions](./util.md#emulatormocktokenoptions) \| string; } | | + +Returns: + +void + +## doc() + +Gets a `DocumentReference` instance that refers to the document at the specified absolute path. + +Signature: + +```typescript +export declare function doc(firestore: Firestore, path: string, ...pathSegments: string[]): DocumentReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | A reference to the root Firestore instance. | +| path | string | A slash-separated path to a document. | +| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | + +Returns: + +[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> + +The `DocumentReference` instance. + +## Exceptions + +If the final path has an odd number of segments and does not point to a document. + +## runTransaction() + +Executes the given `updateFunction` and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, Cloud Firestore retries the `updateFunction`. If it fails to commit after 5 attempts, the transaction fails. + +The maximum number of writes allowed in a single transaction is 500. + +Signature: + +```typescript +export declare function runTransaction(firestore: Firestore, updateFunction: (transaction: Transaction) => Promise, options?: TransactionOptions): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | A reference to the Firestore database to run this transaction against. | +| updateFunction | (transaction: [Transaction](./firestore_lite.transaction.md#transaction_class)) => Promise<T> | The function to execute within the transaction context. | +| options | [TransactionOptions](./firestore_lite.transactionoptions.md#transactionoptions_interface) | An options object to configure maximum number of attempts to commit. | + +Returns: + +Promise<T> + +If the transaction completed successfully or was explicitly aborted (the `updateFunction` returned a failed promise), the promise returned by the `updateFunction `is returned here. Otherwise, if the transaction failed, a rejected promise with the corresponding failure error is returned. + +## terminate() + +Terminates the provided `Firestore` instance. + +After calling `terminate()` only the `clearIndexedDbPersistence()` functions may be used. Any other function will throw a `FirestoreError`. Termination does not cancel any pending writes, and any promises that are awaiting a response from the server will not be resolved. + +To restart after termination, create a new instance of `Firestore` with [getFirestore()](./firestore_.md#getfirestore). + +Note: Under normal circumstances, calling `terminate()` is not required. This function is useful only when you want to force this instance to release all of its resources or in combination with [clearIndexedDbPersistence()](./firestore_.md#clearindexeddbpersistence) to ensure that all local state is destroyed between test runs. + +Signature: + +```typescript +export declare function terminate(firestore: Firestore): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | The Firestore instance to terminate. | + +Returns: + +Promise<void> + +A `Promise` that is resolved when the instance has been successfully terminated. + +## writeBatch() + +Creates a write batch, used for performing multiple writes as a single atomic operation. The maximum number of writes allowed in a single WriteBatch is 500. + +The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. + +Signature: + +```typescript +export declare function writeBatch(firestore: Firestore): WriteBatch; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | | + +Returns: + +[WriteBatch](./firestore_lite.writebatch.md#writebatch_class) + +A `WriteBatch` that can be used to atomically execute multiple writes. + +## deleteField() + +Returns a sentinel for use with [updateDoc()](./firestore_lite.md#updatedoc) or [setDoc()](./firestore_lite.md#setdoc) with `{merge: true}` to mark a field for deletion. + +Signature: + +```typescript +export declare function deleteField(): FieldValue; +``` +Returns: + +[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) + +## documentId() + +Returns a special sentinel `FieldPath` to refer to the ID of a document. It can be used in queries to sort or filter by the document ID. + +Signature: + +```typescript +export declare function documentId(): FieldPath; +``` +Returns: + +[FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) + +## getFirestore() + +Returns the existing default [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: + +```typescript +export declare function getFirestore(): Firestore; +``` +Returns: + +[Firestore](./firestore_lite.firestore.md#firestore_class) + +The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. + +## 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. + +Signature: + +```typescript +export declare function serverTimestamp(): FieldValue; +``` +Returns: + +[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) + +## 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. + +Signature: + +```typescript +export declare function arrayRemove(...elements: unknown[]): FieldValue; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| elements | unknown\[\] | The elements to remove from the array. | + +Returns: + +[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) + +The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()` + +## 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. + +Signature: + +```typescript +export declare function arrayUnion(...elements: unknown[]): FieldValue; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| elements | unknown\[\] | The elements to union into the array. | + +Returns: + +[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) + +The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()`. + +## orderBy() + +Creates a [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class) that sorts the query result by the specified field, optionally in descending order instead of ascending. + +Note: Documents that do not contain the specified field will not be present in the query result. + +Signature: + +```typescript +export declare function orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDirection): QueryOrderByConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldPath | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The field to sort by. | +| directionStr | [OrderByDirection](./firestore_lite.md#orderbydirection) | Optional direction to sort by ('asc' or 'desc'). If not specified, order will be ascending. | + +Returns: + +[QueryOrderByConstraint](./firestore_lite.queryorderbyconstraint.md#queryorderbyconstraint_class) + +The created [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class). + +## where() + +Creates a [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) that enforces that documents must contain the specified field and that the value should satisfy the relation constraint provided. + +Signature: + +```typescript +export declare function where(fieldPath: string | FieldPath, opStr: WhereFilterOp, value: unknown): QueryFieldFilterConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldPath | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The path to compare | +| opStr | [WhereFilterOp](./firestore_lite.md#wherefilterop) | The operation string (e.g "&lt;", "&lt;=", "==", "&lt;", "&lt;=", "!="). | +| value | unknown | The value for comparison | + +Returns: + +[QueryFieldFilterConstraint](./firestore_lite.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) + +The created [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class). + +## endAt() + +Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. + +Signature: + +```typescript +export declare function endAt(...fieldValues: unknown[]): QueryEndAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldValues | unknown\[\] | The field values to end this query at, in order of the query's order by. | + +Returns: + +[QueryEndAtConstraint](./firestore_lite.queryendatconstraint.md#queryendatconstraint_class) + +A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` + +## endBefore() + +Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. + +Signature: + +```typescript +export declare function endBefore(...fieldValues: unknown[]): QueryEndAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldValues | unknown\[\] | The field values to end this query before, in order of the query's order by. | + +Returns: + +[QueryEndAtConstraint](./firestore_lite.queryendatconstraint.md#queryendatconstraint_class) + +A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` + +## startAfter() + +Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. + +Signature: + +```typescript +export declare function startAfter(...fieldValues: unknown[]): QueryStartAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldValues | unknown\[\] | The field values to start this query after, in order of the query's order by. | + +Returns: + +[QueryStartAtConstraint](./firestore_lite.querystartatconstraint.md#querystartatconstraint_class) + +A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()` + +## startAt() + +Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. + +Signature: + +```typescript +export declare function startAt(...fieldValues: unknown[]): QueryStartAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldValues | unknown\[\] | The field values to start this query at, in order of the query's order by. | + +Returns: + +[QueryStartAtConstraint](./firestore_lite.querystartatconstraint.md#querystartatconstraint_class) + +A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()`. + +## aggregateQuerySnapshotEqual() + +Compares two `AggregateQuerySnapshot` instances for equality. + +Two `AggregateQuerySnapshot` instances are considered "equal" if they have underlying queries that compare equal, and the same data. + +Signature: + +```typescript +export declare function aggregateQuerySnapshotEqual(left: AggregateQuerySnapshot, right: AggregateQuerySnapshot): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| left | [AggregateQuerySnapshot](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<T> | The first AggregateQuerySnapshot to compare. | +| right | [AggregateQuerySnapshot](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<T> | The second AggregateQuerySnapshot to compare. | + +Returns: + +boolean + +`true` if the objects are "equal", as defined above, or `false` otherwise. + +## queryEqual() + +Returns true if the provided queries point to the same collection and apply the same constraints. + +Signature: + +```typescript +export declare function queryEqual(left: Query, right: Query): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| left | [Query](./firestore_lite.query.md#query_class)<T> | A Query to compare. | +| right | [Query](./firestore_lite.query.md#query_class)<T> | A Query to compare. | + +Returns: + +boolean + +true if the references point to the same location in the same Firestore database. + +## refEqual() + +Returns true if the provided references are equal. + +Signature: + +```typescript +export declare function refEqual(left: DocumentReference | CollectionReference, right: DocumentReference | CollectionReference): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| left | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> \| [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | A reference to compare. | +| right | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> \| [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | A reference to compare. | + +Returns: + +boolean + +true if the references point to the same location in the same Firestore database. + +## snapshotEqual() + +Returns true if the provided snapshots are equal. + +Signature: + +```typescript +export declare function snapshotEqual(left: DocumentSnapshot | QuerySnapshot, right: DocumentSnapshot | QuerySnapshot): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| left | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<T> \| [QuerySnapshot](./firestore_lite.querysnapshot.md#querysnapshot_class)<T> | A snapshot to compare. | +| right | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<T> \| [QuerySnapshot](./firestore_lite.querysnapshot.md#querysnapshot_class)<T> | A snapshot to compare. | + +Returns: + +boolean + +true if the snapshots are equal. + +## limit() + +Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the first matching documents. + +Signature: + +```typescript +export declare function limit(limit: number): QueryLimitConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| limit | number | The maximum number of items to return. | + +Returns: + +[QueryLimitConstraint](./firestore_lite.querylimitconstraint.md#querylimitconstraint_class) + +The created [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class). + +## limitToLast() + +Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the last matching documents. + +You must specify at least one `orderBy` clause for `limitToLast` queries, otherwise an exception will be thrown during execution. + +Signature: + +```typescript +export declare function limitToLast(limit: number): QueryLimitConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| limit | number | The maximum number of items to return. | + +Returns: + +[QueryLimitConstraint](./firestore_lite.querylimitconstraint.md#querylimitconstraint_class) + +The created [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class). + +## setLogLevel() + +Sets the verbosity of Cloud Firestore logs (debug, error, or silent). + +Signature: + +```typescript +export declare function setLogLevel(logLevel: LogLevel): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| logLevel | LogLevel | The verbosity you set for activity and error logging. Can be any of the following values:
  • debug for the most verbose logging level, primarily for debugging.
  • error to log errors only.
  • silent to turn off logging.
| + +Returns: + +void + +## increment() + +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 increment the field's current value by the given value. + +If either the operand or the current field value uses floating point precision, all arithmetic follows IEEE 754 semantics. If both values are integers, values outside of JavaScript's safe number range (`Number.MIN_SAFE_INTEGER` to `Number.MAX_SAFE_INTEGER`) are also subject to precision loss. Furthermore, once processed by the Firestore backend, all integer operations are capped between -2^63 and 2^63-1. + +If the current field value is not of type `number`, or if the field does not yet exist, the transformation sets the field to the given value. + +Signature: + +```typescript +export declare function increment(n: number): FieldValue; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| n | number | The value to increment by. | + +Returns: + +[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) + +The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()` + +## getCount() + +Calculates the number of documents in the result set of the given query, without actually downloading the documents. + +Using this function to count the documents is efficient because only the final count, not the documents' data, is downloaded. This function can even count the documents if the result set would be prohibitively large to download entirely (e.g. thousands of documents). + +Signature: + +```typescript +export declare function getCount(query: Query): Promise; +}>>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./firestore_lite.query.md#query_class)<unknown> | The query whose result set size to calculate. | + +Returns: + +Promise<[AggregateQuerySnapshot](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<{ count: [AggregateField](./firestore_lite.aggregatefield.md#aggregatefield_class)<number>; }>> + +A Promise that will be resolved with the count; the count can be retrieved from `snapshot.data().count`, where `snapshot` is the `AggregateQuerySnapshot` to which the returned Promise resolves. + +## getDocs() + +Executes the query and returns the results as a [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class). + +All queries are executed directly by the server, even if the the query was previously executed. Recent modifications are only reflected in the retrieved results if they have already been applied by the backend. If the client is offline, the operation fails. To see previously cached result and local modifications, use the full Firestore SDK. + +Signature: + +```typescript +export declare function getDocs(query: Query): Promise>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./firestore_lite.query.md#query_class)<T> | The Query to execute. | + +Returns: + +Promise<[QuerySnapshot](./firestore_lite.querysnapshot.md#querysnapshot_class)<T>> + +A Promise that will be resolved with the results of the query. + +## query() + +Creates a new immutable instance of [Query](./firestore_.query.md#query_class) that is extended to also include additional query constraints. + +Signature: + +```typescript +export declare function query(query: Query, ...queryConstraints: QueryConstraint[]): Query; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./firestore_lite.query.md#query_class)<T> | The [Query](./firestore_.query.md#query_class) instance to use as a base for the new constraints. | +| queryConstraints | [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class)\[\] | The list of [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class)s to apply. | + +Returns: + +[Query](./firestore_lite.query.md#query_class)<T> + +## Exceptions + +if any of the provided query constraints cannot be combined with the existing or new constraints. + +## addDoc() + +Add a new document to specified `CollectionReference` with the given data, assigning it a document ID automatically. + +The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. + +Signature: + +```typescript +export declare function addDoc(reference: CollectionReference, data: WithFieldValue): Promise>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | A reference to the collection to add this document to. | +| data | [WithFieldValue](./firestore_lite.md#withfieldvalue)<T> | An Object containing the data for the new document. | + +Returns: + +Promise<[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T>> + +A `Promise` resolved with a `DocumentReference` pointing to the newly created document after it has been written to the backend. + +## Exceptions + +Error - If the provided input is not a valid Firestore document. + +## collection() + +Gets a `CollectionReference` instance that refers to a subcollection of `reference` at the the specified relative path. + +Signature: + +```typescript +export declare function collection(reference: CollectionReference, path: string, ...pathSegments: string[]): CollectionReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<unknown> | A reference to a collection. | +| path | string | A slash-separated path to a collection. | +| pathSegments | string\[\] | Additional path segments to apply relative to the first argument. | + +Returns: + +[CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> + +The `CollectionReference` instance. + +## Exceptions + +If the final path has an even number of segments and does not point to a collection. + +## collection() + +Gets a `CollectionReference` instance that refers to a subcollection of `reference` at the the specified relative path. + +Signature: + +```typescript +export declare function collection(reference: DocumentReference, path: string, ...pathSegments: string[]): CollectionReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class) | A reference to a Firestore document. | +| path | string | A slash-separated path to a collection. | +| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | + +Returns: + +[CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> + +The `CollectionReference` instance. + +## Exceptions + +If the final path has an even number of segments and does not point to a collection. + +## deleteDoc() + +Deletes the document referred to by the specified `DocumentReference`. + +The deletion will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the delete fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. + +Signature: + +```typescript +export declare function deleteDoc(reference: DocumentReference): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to the document to delete. | + +Returns: + +Promise<void> + +A `Promise` resolved once the document has been successfully deleted from the backend. + +## doc() + +Gets a `DocumentReference` instance that refers to a document within `reference` at the specified relative path. If no path is specified, an automatically-generated unique ID will be used for the returned `DocumentReference`. + +Signature: + +```typescript +export declare function doc(reference: CollectionReference, path?: string, ...pathSegments: string[]): DocumentReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | A reference to a collection. | +| path | string | A slash-separated path to a document. Has to be omitted to use auto-genrated IDs. | +| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | + +Returns: + +[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> + +The `DocumentReference` instance. + +## Exceptions + +If the final path has an odd number of segments and does not point to a document. + +## doc() + +Gets a `DocumentReference` instance that refers to a document within `reference` at the specified relative path. + +Signature: + +```typescript +export declare function doc(reference: DocumentReference, path: string, ...pathSegments: string[]): DocumentReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to a Firestore document. | +| path | string | A slash-separated path to a document. | +| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | + +Returns: + +[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> + +The `DocumentReference` instance. + +## Exceptions + +If the final path has an odd number of segments and does not point to a document. + +## getDoc() + +Reads the document referred to by the specified document reference. + +All documents are directly fetched from the server, even if the document was previously read or modified. Recent modifications are only reflected in the retrieved `DocumentSnapshot` if they have already been applied by the backend. If the client is offline, the read fails. If you like to use caching or see local modifications, please use the full Firestore SDK. + +Signature: + +```typescript +export declare function getDoc(reference: DocumentReference): Promise>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | The reference of the document to fetch. | + +Returns: + +Promise<[DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<T>> + +A Promise resolved with a `DocumentSnapshot` containing the current document contents. + +## setDoc() + +Writes to the document referred to by the specified `DocumentReference`. If the document does not yet exist, it will be created. + +The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. + +Signature: + +```typescript +export declare function setDoc(reference: DocumentReference, data: WithFieldValue): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to write. | +| data | [WithFieldValue](./firestore_lite.md#withfieldvalue)<T> | A map of the fields and values for the document. | + +Returns: + +Promise<void> + +A `Promise` resolved once the data has been successfully written to the backend. + +## Exceptions + +Error - If the provided input is not a valid Firestore document. + +## setDoc() + +Writes to the document referred to by the specified `DocumentReference`. If the document does not yet exist, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. + +The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. + +Signature: + +```typescript +export declare function setDoc(reference: DocumentReference, data: PartialWithFieldValue, options: SetOptions): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to write. | +| data | [PartialWithFieldValue](./firestore_lite.md#partialwithfieldvalue)<T> | A map of the fields and values for the document. | +| options | [SetOptions](./firestore_lite.md#setoptions) | An object to configure the set behavior. | + +Returns: + +Promise<void> + +A `Promise` resolved once the data has been successfully written to the backend. + +## Exceptions + +Error - If the provided input is not a valid Firestore document. + +## updateDoc() + +Updates fields in the document referred to by the specified `DocumentReference`. The update will fail if applied to a document that does not exist. + +The result of this update will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the update fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. + +Signature: + +```typescript +export declare function updateDoc(reference: DocumentReference, data: UpdateData): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to update. | +| data | [UpdateData](./firestore_lite.md#updatedata)<T> | An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document. | + +Returns: + +Promise<void> + +A `Promise` resolved once the data has been successfully written to the backend. + +## Exceptions + +Error - If the provided input is not valid Firestore data. + +## updateDoc() + +Updates fields in the document referred to by the specified `DocumentReference` The update will fail if applied to a document that does not exist. + +Nested fields can be updated by providing dot-separated field path strings or by providing `FieldPath` objects. + +The result of this update will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the update fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. + +Signature: + +```typescript +export declare function updateDoc(reference: DocumentReference, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to the document to update. | +| field | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The first field to update. | +| value | unknown | The first value. | +| moreFieldsAndValues | unknown\[\] | Additional key value pairs. | + +Returns: + +Promise<void> + +A `Promise` resolved once the data has been successfully written to the backend. + +## Exceptions + +Error - If the provided input is not valid Firestore data. + +## endAt() + +Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided document (inclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. + +Signature: + +```typescript +export declare function endAt(snapshot: DocumentSnapshot): QueryEndAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| snapshot | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to end at. | + +Returns: + +[QueryEndAtConstraint](./firestore_lite.queryendatconstraint.md#queryendatconstraint_class) + +A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` + +## endBefore() + +Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. + +Signature: + +```typescript +export declare function endBefore(snapshot: DocumentSnapshot): QueryEndAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| snapshot | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to end before. | + +Returns: + +[QueryEndAtConstraint](./firestore_lite.queryendatconstraint.md#queryendatconstraint_class) + +A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` + +## startAfter() + +Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. + +Signature: + +```typescript +export declare function startAfter(snapshot: DocumentSnapshot): QueryStartAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| snapshot | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to start after. | + +Returns: + +[QueryStartAtConstraint](./firestore_lite.querystartatconstraint.md#querystartatconstraint_class) + +A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()` + +## startAt() + +Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the `orderBy` of this query. + +Signature: + +```typescript +export declare function startAt(snapshot: DocumentSnapshot): QueryStartAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| snapshot | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to start at. | + +Returns: + +[QueryStartAtConstraint](./firestore_lite.querystartatconstraint.md#querystartatconstraint_class) + +A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()`. + +## AddPrefixToKeys + +Returns a new map where every key is prefixed with the outer key appended to a dot. + +Signature: + +```typescript +export declare type AddPrefixToKeys> = { + [K in keyof T & string as `${Prefix}.${K}`]+?: T[K]; +}; +``` + +## AggregateFieldType + +The union of all `AggregateField` types that are supported by Firestore. + +Signature: + +```typescript +export declare type AggregateFieldType = AggregateField; +``` + +## AggregateSpecData + +A type whose keys are taken from an `AggregateSpec`, and whose values are the result of the aggregation performed by the corresponding `AggregateField` from the input `AggregateSpec`. + +Signature: + +```typescript +export declare type AggregateSpecData = { + [P in keyof T]: T[P] extends AggregateField ? U : never; +}; +``` + +## ChildUpdateFields + +Helper for calculating the nested fields for a given type T1. This is needed to distribute union types such as `undefined | {...}` (happens for optional props) or `{a: A} | {b: B}`. + +In this use case, `V` is used to distribute the union types of `T[K]` on `Record`, since `T[K]` is evaluated as an expression and not distributed. + +See https://www.typescriptlang.org/docs/handbook/advanced-types.html\#distributive-conditional-types + +Signature: + +```typescript +export declare type ChildUpdateFields = V extends Record ? AddPrefixToKeys> : never; +``` + +## FirestoreErrorCode + +The set of Firestore status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.md + +Possible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (e.g. an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation. + +Signature: + +```typescript +export declare type FirestoreErrorCode = 'cancelled' | 'unknown' | 'invalid-argument' | 'deadline-exceeded' | 'not-found' | 'already-exists' | 'permission-denied' | 'resource-exhausted' | 'failed-precondition' | 'aborted' | 'out-of-range' | 'unimplemented' | 'internal' | 'unavailable' | 'data-loss' | 'unauthenticated'; +``` + +## NestedUpdateFields + +For each field (e.g. 'bar'), find all nested keys (e.g. {'bar.baz': T1, 'bar.qux': T2}). Intersect them together to make a single map containing all possible keys that are all marked as optional + +Signature: + +```typescript +export declare type NestedUpdateFields> = UnionToIntersection<{ + [K in keyof T & string]: ChildUpdateFields; +}[keyof T & string]>; +``` + +## OrderByDirection + +The direction of a [orderBy()](./firestore_.md#orderby) clause is specified as 'desc' or 'asc' (descending or ascending). + +Signature: + +```typescript +export declare type OrderByDirection = 'desc' | 'asc'; +``` + +## PartialWithFieldValue + +Similar to Typescript's `Partial`, but allows nested fields to be omitted and FieldValues to be passed in as property values. + +Signature: + +```typescript +export declare type PartialWithFieldValue = Partial | (T extends Primitive ? T : T extends {} ? { + [K in keyof T]?: PartialWithFieldValue | FieldValue; +} : never); +``` + +## Primitive + +Primitive types. + +Signature: + +```typescript +export declare type Primitive = string | number | boolean | undefined | null; +``` + +## QueryConstraintType + +Describes the different query constraints available in this SDK. + +Signature: + +```typescript +export declare type QueryConstraintType = 'where' | 'orderBy' | 'limit' | 'limitToLast' | 'startAt' | 'startAfter' | 'endAt' | 'endBefore'; +``` + +## QueryNonFilterConstraint + +`QueryNonFilterConstraint` is a helper union type that represents QueryConstraints which are used to narrow or order the set of documents, but that do not explicitly filter on a document field. `QueryNonFilterConstraint`s are created by invoking [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains the `QueryConstraint`. + +Signature: + +```typescript +export declare type QueryNonFilterConstraint = QueryOrderByConstraint | QueryLimitConstraint | QueryStartAtConstraint | QueryEndAtConstraint; +``` + +## SetOptions + +An options object that configures the behavior of [setDoc()](./firestore_lite.md#setdoc), and calls. These calls can be configured to perform granular merges instead of overwriting the target documents in their entirety by providing a `SetOptions` with `merge: true`. + +Signature: + +```typescript +export declare type SetOptions = { + readonly merge?: boolean; +} | { + readonly mergeFields?: Array; +}; +``` + +## UnionToIntersection + +Given a union type `U = T1 | T2 | ...`, returns an intersected type `(T1 & T2 & ...)`. + +Uses distributive conditional types and inference from conditional types. This works because multiple candidates for the same type variable in contra-variant positions causes an intersection type to be inferred. https://www.typescriptlang.org/docs/handbook/advanced-types.html\#type-inference-in-conditional-types https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection-type + +Signature: + +```typescript +export declare type UnionToIntersection = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never; +``` + +## UpdateData + +Update data (for use with [updateDoc()](./firestore_.md#updatedoc)) that consists of field paths (e.g. 'foo' or 'foo.baz') mapped to values. Fields that contain dots reference nested fields within the document. FieldValues can be passed in as property values. + +Signature: + +```typescript +export declare type UpdateData = T extends Primitive ? T : T extends {} ? { + [K in keyof T]?: UpdateData | FieldValue; +} & NestedUpdateFields : Partial; +``` + +## WhereFilterOp + +Filter conditions in a [where()](./firestore_.md#where) clause are specified using the strings '&lt;', '&lt;=', '==', '!=', '&gt;=', '&gt;', 'array-contains', 'in', 'array-contains-any', and 'not-in'. + +Signature: + +```typescript +export declare type WhereFilterOp = '<' | '<=' | '==' | '!=' | '>=' | '>' | 'array-contains' | 'in' | 'array-contains-any' | 'not-in'; +``` + +## WithFieldValue + +Allows FieldValues to be passed in as a property value while maintaining type safety. + +Signature: + +```typescript +export declare type WithFieldValue = T | (T extends Primitive ? T : T extends {} ? { + [K in keyof T]: WithFieldValue | FieldValue; +} : never); +``` diff --git a/docs-devsite/firestore_lite.query.md b/docs-devsite/firestore_lite.query.md new file mode 100644 index 00000000000..f2eac7560dc --- /dev/null +++ b/docs-devsite/firestore_lite.query.md @@ -0,0 +1,125 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Query class +A `Query` refers to a query which you can read or listen to. You can also construct refined `Query` objects by adding filters and ordering. + +Signature: + +```typescript +export declare class Query +``` + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)()](./firestore_lite.query.md#queryconstructor) | | Constructs a new instance of the Query class | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [converter](./firestore_lite.query.md#queryconverter) | | [FirestoreDataConverter](./firestore_lite.firestoredataconverter.md#firestoredataconverter_interface)<T> \| null | If provided, the FirestoreDataConverter associated with this instance. | +| [firestore](./firestore_lite.query.md#queryfirestore) | | [Firestore](./firestore_lite.firestore.md#firestore_class) | The Firestore instance for the Firestore database (useful for performing transactions, etc.). | +| [type](./firestore_lite.query.md#querytype) | | 'query' \| 'collection' | The type of this Firestore reference. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [withConverter(converter)](./firestore_lite.query.md#querywithconverter) | | Removes the current converter. | +| [withConverter(converter)](./firestore_lite.query.md#querywithconverter) | | Applies a custom data converter to this query, allowing you to use your own custom model objects with Firestore. When you call [getDocs()](./firestore_.md#getdocs) with the returned query, the provided converter will convert between Firestore data and your custom type U. | + +## Query.(constructor) + +Constructs a new instance of the `Query` class + +Signature: + +```typescript +protected constructor(); +``` + +## Query.converter + +If provided, the `FirestoreDataConverter` associated with this instance. + +Signature: + +```typescript +readonly converter: FirestoreDataConverter | null; +``` + +## Query.firestore + +The `Firestore` instance for the Firestore database (useful for performing transactions, etc.). + +Signature: + +```typescript +readonly firestore: Firestore; +``` + +## Query.type + +The type of this Firestore reference. + +Signature: + +```typescript +readonly type: 'query' | 'collection'; +``` + +## Query.withConverter() + +Removes the current converter. + +Signature: + +```typescript +withConverter(converter: null): Query; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| converter | null | null removes the current converter. | + +Returns: + +[Query](./firestore_lite.query.md#query_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> + +A `Query` that does not use a converter. + +## Query.withConverter() + +Applies a custom data converter to this query, allowing you to use your own custom model objects with Firestore. When you call [getDocs()](./firestore_.md#getdocs) with the returned query, the provided converter will convert between Firestore data and your custom type `U`. + +Signature: + +```typescript +withConverter(converter: FirestoreDataConverter): Query; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| converter | [FirestoreDataConverter](./firestore_lite.firestoredataconverter.md#firestoredataconverter_interface)<U> | Converts objects to and from Firestore. | + +Returns: + +[Query](./firestore_lite.query.md#query_class)<U> + +A `Query` that uses the provided converter. + diff --git a/docs-devsite/firestore_lite.queryconstraint.md b/docs-devsite/firestore_lite.queryconstraint.md new file mode 100644 index 00000000000..dae8d5f0069 --- /dev/null +++ b/docs-devsite/firestore_lite.queryconstraint.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryConstraint class +A `QueryConstraint` is used to narrow the set of documents returned by a Firestore query. `QueryConstraint`s are created by invoking [where()](./firestore_.md#where), [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit), [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryConstraint`. + +Signature: + +```typescript +export declare abstract class QueryConstraint +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_lite.queryconstraint.md#queryconstrainttype) | | [QueryConstraintType](./firestore_lite.md#queryconstrainttype) | The type of this query constraint | + +## QueryConstraint.type + +The type of this query constraint + +Signature: + +```typescript +abstract readonly type: QueryConstraintType; +``` diff --git a/docs-devsite/firestore_lite.querydocumentsnapshot.md b/docs-devsite/firestore_lite.querydocumentsnapshot.md new file mode 100644 index 00000000000..356d7ecaeed --- /dev/null +++ b/docs-devsite/firestore_lite.querydocumentsnapshot.md @@ -0,0 +1,45 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryDocumentSnapshot class +A `QueryDocumentSnapshot` contains data read from a document in your Firestore database as part of a query. The document is guaranteed to exist and its data can be extracted with `.data()` or `.get()` to get a specific field. + +A `QueryDocumentSnapshot` offers the same API surface as a `DocumentSnapshot`. Since query results contain only existing documents, the `exists` property will always be true and `data()` will never return 'undefined'. + +Signature: + +```typescript +export declare class QueryDocumentSnapshot extends DocumentSnapshot +``` +Extends: [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<T> + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [data()](./firestore_lite.querydocumentsnapshot.md#querydocumentsnapshotdata) | | Retrieves all fields in the document as an Object. | + +## QueryDocumentSnapshot.data() + +Retrieves all fields in the document as an `Object`. + +Signature: + +```typescript +/** @override */ +data(): T; +``` +Returns: + +T + +An `Object` containing all fields in the document. + diff --git a/docs-devsite/firestore_lite.queryendatconstraint.md b/docs-devsite/firestore_lite.queryendatconstraint.md new file mode 100644 index 00000000000..7f999a414b6 --- /dev/null +++ b/docs-devsite/firestore_lite.queryendatconstraint.md @@ -0,0 +1,36 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryEndAtConstraint class +A `QueryEndAtConstraint` is used to exclude documents from the end of a result set returned by a Firestore query. `QueryEndAtConstraint`s are created by invoking [endAt()](./firestore_.md#endat) or [endBefore()](./firestore_.md#endbefore) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryEndAtConstraint`. + +Signature: + +```typescript +export declare class QueryEndAtConstraint extends QueryConstraint +``` +Extends: [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_lite.queryendatconstraint.md#queryendatconstrainttype) | | 'endBefore' \| 'endAt' | The type of this query constraint | + +## QueryEndAtConstraint.type + +The type of this query constraint + +Signature: + +```typescript +readonly type: 'endBefore' | 'endAt'; +``` diff --git a/docs-devsite/firestore_lite.queryfieldfilterconstraint.md b/docs-devsite/firestore_lite.queryfieldfilterconstraint.md new file mode 100644 index 00000000000..81c1509223d --- /dev/null +++ b/docs-devsite/firestore_lite.queryfieldfilterconstraint.md @@ -0,0 +1,36 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryFieldFilterConstraint class +A `QueryFieldFilterConstraint` is used to narrow the set of documents returned by a Firestore query by filtering on one or more document fields. `QueryFieldFilterConstraint`s are created by invoking [where()](./firestore_.md#where) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryFieldFilterConstraint`. + +Signature: + +```typescript +export declare class QueryFieldFilterConstraint extends QueryConstraint +``` +Extends: [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_lite.queryfieldfilterconstraint.md#queryfieldfilterconstrainttype) | | (not declared) | The type of this query constraint | + +## QueryFieldFilterConstraint.type + +The type of this query constraint + +Signature: + +```typescript +readonly type = "where"; +``` diff --git a/docs-devsite/firestore_lite.querylimitconstraint.md b/docs-devsite/firestore_lite.querylimitconstraint.md new file mode 100644 index 00000000000..82218279e34 --- /dev/null +++ b/docs-devsite/firestore_lite.querylimitconstraint.md @@ -0,0 +1,36 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryLimitConstraint class +A `QueryLimitConstraint` is used to limit the number of documents returned by a Firestore query. `QueryLimitConstraint`s are created by invoking [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryLimitConstraint`. + +Signature: + +```typescript +export declare class QueryLimitConstraint extends QueryConstraint +``` +Extends: [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_lite.querylimitconstraint.md#querylimitconstrainttype) | | 'limit' \| 'limitToLast' | The type of this query constraint | + +## QueryLimitConstraint.type + +The type of this query constraint + +Signature: + +```typescript +readonly type: 'limit' | 'limitToLast'; +``` diff --git a/docs-devsite/firestore_lite.queryorderbyconstraint.md b/docs-devsite/firestore_lite.queryorderbyconstraint.md new file mode 100644 index 00000000000..b5a28ed3e9a --- /dev/null +++ b/docs-devsite/firestore_lite.queryorderbyconstraint.md @@ -0,0 +1,38 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryOrderByConstraint class +A `QueryOrderByConstraint` is used to sort the set of documents returned by a Firestore query. `QueryOrderByConstraint`s are created by invoking [orderBy()](./firestore_.md#orderby) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryOrderByConstraint`. + +Note: Documents that do not contain the orderBy field will not be present in the query result. + +Signature: + +```typescript +export declare class QueryOrderByConstraint extends QueryConstraint +``` +Extends: [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_lite.queryorderbyconstraint.md#queryorderbyconstrainttype) | | (not declared) | The type of this query constraint | + +## QueryOrderByConstraint.type + +The type of this query constraint + +Signature: + +```typescript +readonly type = "orderBy"; +``` diff --git a/docs-devsite/firestore_lite.querysnapshot.md b/docs-devsite/firestore_lite.querysnapshot.md new file mode 100644 index 00000000000..8e805af948d --- /dev/null +++ b/docs-devsite/firestore_lite.querysnapshot.md @@ -0,0 +1,96 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QuerySnapshot class +A `QuerySnapshot` contains zero or more `DocumentSnapshot` objects representing the results of a query. The documents can be accessed as an array via the `docs` property or enumerated using the `forEach` method. The number of documents can be determined via the `empty` and `size` properties. + +Signature: + +```typescript +export declare class QuerySnapshot +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [docs](./firestore_lite.querysnapshot.md#querysnapshotdocs) | | Array<[QueryDocumentSnapshot](./firestore_lite.querydocumentsnapshot.md#querydocumentsnapshot_class)<T>> | An array of all the documents in the QuerySnapshot. | +| [empty](./firestore_lite.querysnapshot.md#querysnapshotempty) | | boolean | True if there are no documents in the QuerySnapshot. | +| [query](./firestore_lite.querysnapshot.md#querysnapshotquery) | | [Query](./firestore_lite.query.md#query_class)<T> | The query on which you called [getDocs()](./firestore_.md#getdocs) in order to get this QuerySnapshot. | +| [size](./firestore_lite.querysnapshot.md#querysnapshotsize) | | number | The number of documents in the QuerySnapshot. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [forEach(callback, thisArg)](./firestore_lite.querysnapshot.md#querysnapshotforeach) | | Enumerates all of the documents in the QuerySnapshot. | + +## QuerySnapshot.docs + +An array of all the documents in the `QuerySnapshot`. + +Signature: + +```typescript +get docs(): Array>; +``` + +## QuerySnapshot.empty + +True if there are no documents in the `QuerySnapshot`. + +Signature: + +```typescript +get empty(): boolean; +``` + +## QuerySnapshot.query + +The query on which you called [getDocs()](./firestore_.md#getdocs) in order to get this `QuerySnapshot`. + +Signature: + +```typescript +readonly query: Query; +``` + +## QuerySnapshot.size + +The number of documents in the `QuerySnapshot`. + +Signature: + +```typescript +get size(): number; +``` + +## QuerySnapshot.forEach() + +Enumerates all of the documents in the `QuerySnapshot`. + +Signature: + +```typescript +forEach(callback: (result: QueryDocumentSnapshot) => void, thisArg?: unknown): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| callback | (result: [QueryDocumentSnapshot](./firestore_lite.querydocumentsnapshot.md#querydocumentsnapshot_class)<T>) => void | A callback to be called with a QueryDocumentSnapshot for each document in the snapshot. | +| thisArg | unknown | The this binding for the callback. | + +Returns: + +void + diff --git a/docs-devsite/firestore_lite.querystartatconstraint.md b/docs-devsite/firestore_lite.querystartatconstraint.md new file mode 100644 index 00000000000..08d6ba15103 --- /dev/null +++ b/docs-devsite/firestore_lite.querystartatconstraint.md @@ -0,0 +1,36 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryStartAtConstraint class +A `QueryStartAtConstraint` is used to exclude documents from the start of a result set returned by a Firestore query. `QueryStartAtConstraint`s are created by invoking [startAt()](./firestore_.md#startat) or [startAfter()](./firestore_.md#startafter) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryStartAtConstraint`. + +Signature: + +```typescript +export declare class QueryStartAtConstraint extends QueryConstraint +``` +Extends: [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_lite.querystartatconstraint.md#querystartatconstrainttype) | | 'startAt' \| 'startAfter' | The type of this query constraint | + +## QueryStartAtConstraint.type + +The type of this query constraint + +Signature: + +```typescript +readonly type: 'startAt' | 'startAfter'; +``` diff --git a/docs-devsite/firestore_lite.settings.md b/docs-devsite/firestore_lite.settings.md new file mode 100644 index 00000000000..ae792a0fc6d --- /dev/null +++ b/docs-devsite/firestore_lite.settings.md @@ -0,0 +1,57 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Settings interface +Specifies custom configurations for your Cloud Firestore instance. You must set these before invoking any other methods. + +Signature: + +```typescript +export declare interface Settings +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [host](./firestore_lite.settings.md#settingshost) | string | The hostname to connect to. | +| [ignoreUndefinedProperties](./firestore_lite.settings.md#settingsignoreundefinedproperties) | boolean | Whether to skip nested properties that are set to undefined during object serialization. If set to true, these properties are skipped and not written to Firestore. If set to false or omitted, the SDK throws an exception when it encounters properties of type undefined. | +| [ssl](./firestore_lite.settings.md#settingsssl) | boolean | Whether to use SSL when connecting. | + +## Settings.host + +The hostname to connect to. + +Signature: + +```typescript +host?: string; +``` + +## Settings.ignoreUndefinedProperties + +Whether to skip nested properties that are set to `undefined` during object serialization. If set to `true`, these properties are skipped and not written to Firestore. If set to `false` or omitted, the SDK throws an exception when it encounters properties of type `undefined`. + +Signature: + +```typescript +ignoreUndefinedProperties?: boolean; +``` + +## Settings.ssl + +Whether to use SSL when connecting. + +Signature: + +```typescript +ssl?: boolean; +``` diff --git a/docs-devsite/firestore_lite.timestamp.md b/docs-devsite/firestore_lite.timestamp.md new file mode 100644 index 00000000000..7b18abc69db --- /dev/null +++ b/docs-devsite/firestore_lite.timestamp.md @@ -0,0 +1,243 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Timestamp class +A `Timestamp` represents a point in time independent of any time zone or calendar, represented as seconds and fractions of seconds at nanosecond resolution in UTC Epoch time. + +It is encoded using the Proleptic Gregorian Calendar which extends the Gregorian calendar backwards to year one. It is encoded assuming all minutes are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. + +For examples and further specifications, refer to the [Timestamp definition](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto). + +Signature: + +```typescript +export declare class Timestamp +``` + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(seconds, nanoseconds)](./firestore_lite.timestamp.md#timestampconstructor) | | Creates a new timestamp. | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [nanoseconds](./firestore_lite.timestamp.md#timestampnanoseconds) | | number | The fractions of a second at nanosecond resolution.\* | +| [seconds](./firestore_lite.timestamp.md#timestampseconds) | | number | The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [fromDate(date)](./firestore_lite.timestamp.md#timestampfromdate) | static | Creates a new timestamp from the given date. | +| [fromMillis(milliseconds)](./firestore_lite.timestamp.md#timestampfrommillis) | static | Creates a new timestamp from the given number of milliseconds. | +| [isEqual(other)](./firestore_lite.timestamp.md#timestampisequal) | | Returns true if this Timestamp is equal to the provided one. | +| [now()](./firestore_lite.timestamp.md#timestampnow) | static | Creates a new timestamp with the current date, with millisecond precision. | +| [toDate()](./firestore_lite.timestamp.md#timestamptodate) | | Converts a Timestamp to a JavaScript Date object. This conversion causes a loss of precision since Date objects only support millisecond precision. | +| [toJSON()](./firestore_lite.timestamp.md#timestamptojson) | | Returns a JSON-serializable representation of this Timestamp. | +| [toMillis()](./firestore_lite.timestamp.md#timestamptomillis) | | Converts a Timestamp to a numeric timestamp (in milliseconds since epoch). This operation causes a loss of precision. | +| [toString()](./firestore_lite.timestamp.md#timestamptostring) | | Returns a textual representation of this Timestamp. | +| [valueOf()](./firestore_lite.timestamp.md#timestampvalueof) | | Converts this object to a primitive string, which allows Timestamp objects to be compared using the >, <=, >= and > operators. | + +## Timestamp.(constructor) + +Creates a new timestamp. + +Signature: + +```typescript +constructor( + seconds: number, + nanoseconds: number); +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| seconds | number | The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive. | +| nanoseconds | number | The non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanoseconds values that count forward in time. Must be from 0 to 999,999,999 inclusive. | + +## Timestamp.nanoseconds + +The fractions of a second at nanosecond resolution.\* + +Signature: + +```typescript +readonly nanoseconds: number; +``` + +## Timestamp.seconds + +The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. + +Signature: + +```typescript +readonly seconds: number; +``` + +## Timestamp.fromDate() + +Creates a new timestamp from the given date. + +Signature: + +```typescript +static fromDate(date: Date): Timestamp; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| date | Date | The date to initialize the Timestamp from. | + +Returns: + +[Timestamp](./firestore_lite.timestamp.md#timestamp_class) + +A new `Timestamp` representing the same point in time as the given date. + +## Timestamp.fromMillis() + +Creates a new timestamp from the given number of milliseconds. + +Signature: + +```typescript +static fromMillis(milliseconds: number): Timestamp; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| milliseconds | number | Number of milliseconds since Unix epoch 1970-01-01T00:00:00Z. | + +Returns: + +[Timestamp](./firestore_lite.timestamp.md#timestamp_class) + +A new `Timestamp` representing the same point in time as the given number of milliseconds. + +## Timestamp.isEqual() + +Returns true if this `Timestamp` is equal to the provided one. + +Signature: + +```typescript +isEqual(other: Timestamp): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| other | [Timestamp](./firestore_lite.timestamp.md#timestamp_class) | The Timestamp to compare against. | + +Returns: + +boolean + +true if this `Timestamp` is equal to the provided one. + +## Timestamp.now() + +Creates a new timestamp with the current date, with millisecond precision. + +Signature: + +```typescript +static now(): Timestamp; +``` +Returns: + +[Timestamp](./firestore_lite.timestamp.md#timestamp_class) + +a new timestamp representing the current date. + +## Timestamp.toDate() + +Converts a `Timestamp` to a JavaScript `Date` object. This conversion causes a loss of precision since `Date` objects only support millisecond precision. + +Signature: + +```typescript +toDate(): Date; +``` +Returns: + +Date + +JavaScript `Date` object representing the same point in time as this `Timestamp`, with millisecond precision. + +## Timestamp.toJSON() + +Returns a JSON-serializable representation of this `Timestamp`. + +Signature: + +```typescript +toJSON(): { + seconds: number; + nanoseconds: number; + }; +``` +Returns: + +{ seconds: number; nanoseconds: number; } + +## Timestamp.toMillis() + +Converts a `Timestamp` to a numeric timestamp (in milliseconds since epoch). This operation causes a loss of precision. + +Signature: + +```typescript +toMillis(): number; +``` +Returns: + +number + +The point in time corresponding to this timestamp, represented as the number of milliseconds since Unix epoch 1970-01-01T00:00:00Z. + +## Timestamp.toString() + +Returns a textual representation of this `Timestamp`. + +Signature: + +```typescript +toString(): string; +``` +Returns: + +string + +## Timestamp.valueOf() + +Converts this object to a primitive string, which allows `Timestamp` objects to be compared using the `>`, `<=`, `>=` and `>` operators. + +Signature: + +```typescript +valueOf(): string; +``` +Returns: + +string + diff --git a/docs-devsite/firestore_lite.transaction.md b/docs-devsite/firestore_lite.transaction.md new file mode 100644 index 00000000000..c643f08d66e --- /dev/null +++ b/docs-devsite/firestore_lite.transaction.md @@ -0,0 +1,190 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Transaction class +A reference to a transaction. + +The `Transaction` object passed to a transaction's `updateFunction` provides the methods to read and write data within the transaction context. See [runTransaction()](./firestore_.md#runtransaction). + +Signature: + +```typescript +export declare class Transaction +``` + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [delete(documentRef)](./firestore_lite.transaction.md#transactiondelete) | | Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). | +| [get(documentRef)](./firestore_lite.transaction.md#transactionget) | | Reads the document referenced by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). | +| [set(documentRef, data)](./firestore_lite.transaction.md#transactionset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. | +| [set(documentRef, data, options)](./firestore_lite.transaction.md#transactionset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document. | +| [update(documentRef, data)](./firestore_lite.transaction.md#transactionupdate) | | Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. | +| [update(documentRef, field, value, moreFieldsAndValues)](./firestore_lite.transaction.md#transactionupdate) | | Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist.Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects. | + +## Transaction.delete() + +Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). + +Signature: + +```typescript +delete(documentRef: DocumentReference): this; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to the document to be deleted. | + +Returns: + +this + +This `Transaction` instance. Used for chaining method calls. + +## Transaction.get() + +Reads the document referenced by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). + +Signature: + +```typescript +get(documentRef: DocumentReference): Promise>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be read. | + +Returns: + +Promise<[DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<T>> + +A `DocumentSnapshot` with the read data. + +## Transaction.set() + +Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. + +Signature: + +```typescript +set(documentRef: DocumentReference, data: WithFieldValue): this; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | +| data | [WithFieldValue](./firestore_lite.md#withfieldvalue)<T> | An object of the fields and values for the document. | + +Returns: + +this + +This `Transaction` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not a valid Firestore document. + +## Transaction.set() + +Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. + +Signature: + +```typescript +set(documentRef: DocumentReference, data: PartialWithFieldValue, options: SetOptions): this; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | +| data | [PartialWithFieldValue](./firestore_lite.md#partialwithfieldvalue)<T> | An object of the fields and values for the document. | +| options | [SetOptions](./firestore_lite.md#setoptions) | An object to configure the set behavior. | + +Returns: + +this + +This `Transaction` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not a valid Firestore document. + +## Transaction.update() + +Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. + +Signature: + +```typescript +update(documentRef: DocumentReference, data: UpdateData): this; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be updated. | +| data | [UpdateData](./firestore_lite.md#updatedata)<T> | An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document. | + +Returns: + +this + +This `Transaction` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not valid Firestore data. + +## Transaction.update() + +Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. + +Nested fields can be updated by providing dot-separated field path strings or by providing `FieldPath` objects. + +Signature: + +```typescript +update(documentRef: DocumentReference, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): this; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to the document to be updated. | +| field | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The first field to update. | +| value | unknown | The first value. | +| moreFieldsAndValues | unknown\[\] | Additional key/value pairs. | + +Returns: + +this + +This `Transaction` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not valid Firestore data. + diff --git a/docs-devsite/firestore_lite.transactionoptions.md b/docs-devsite/firestore_lite.transactionoptions.md new file mode 100644 index 00000000000..94941df172a --- /dev/null +++ b/docs-devsite/firestore_lite.transactionoptions.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# TransactionOptions interface +Options to customize transaction behavior. + +Signature: + +```typescript +export declare interface TransactionOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [maxAttempts](./firestore_lite.transactionoptions.md#transactionoptionsmaxattempts) | number | Maximum number of attempts to commit, after which transaction fails. Default is 5. | + +## TransactionOptions.maxAttempts + +Maximum number of attempts to commit, after which transaction fails. Default is 5. + +Signature: + +```typescript +readonly maxAttempts?: number; +``` diff --git a/docs-devsite/firestore_lite.writebatch.md b/docs-devsite/firestore_lite.writebatch.md new file mode 100644 index 00000000000..141a99e8585 --- /dev/null +++ b/docs-devsite/firestore_lite.writebatch.md @@ -0,0 +1,181 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# WriteBatch class +A write batch, used to perform multiple writes as a single atomic unit. + +A `WriteBatch` object can be acquired by calling [writeBatch()](./firestore_.md#writebatch). It provides methods for adding writes to the write batch. None of the writes will be committed (or visible locally) until [WriteBatch.commit()](./firestore_.writebatch.md#writebatchcommit) is called. + +Signature: + +```typescript +export declare class WriteBatch +``` + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [commit()](./firestore_lite.writebatch.md#writebatchcommit) | | Commits all of the writes in this write batch as a single atomic unit.The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | +| [delete(documentRef)](./firestore_lite.writebatch.md#writebatchdelete) | | Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). | +| [set(documentRef, data)](./firestore_lite.writebatch.md#writebatchset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. | +| [set(documentRef, data, options)](./firestore_lite.writebatch.md#writebatchset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document. | +| [update(documentRef, data)](./firestore_lite.writebatch.md#writebatchupdate) | | Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. | +| [update(documentRef, field, value, moreFieldsAndValues)](./firestore_lite.writebatch.md#writebatchupdate) | | Updates fields in the document referred to by this [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist.Nested fields can be update by providing dot-separated field path strings or by providing FieldPath objects. | + +## WriteBatch.commit() + +Commits all of the writes in this write batch as a single atomic unit. + +The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. + +Signature: + +```typescript +commit(): Promise; +``` +Returns: + +Promise<void> + +A `Promise` resolved once all of the writes in the batch have been successfully written to the backend as an atomic unit (note that it won't resolve while you're offline). + +## WriteBatch.delete() + +Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). + +Signature: + +```typescript +delete(documentRef: DocumentReference): WriteBatch; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to the document to be deleted. | + +Returns: + +[WriteBatch](./firestore_lite.writebatch.md#writebatch_class) + +This `WriteBatch` instance. Used for chaining method calls. + +## WriteBatch.set() + +Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. + +Signature: + +```typescript +set(documentRef: DocumentReference, data: WithFieldValue): WriteBatch; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | +| data | [WithFieldValue](./firestore_lite.md#withfieldvalue)<T> | An object of the fields and values for the document. | + +Returns: + +[WriteBatch](./firestore_lite.writebatch.md#writebatch_class) + +This `WriteBatch` instance. Used for chaining method calls. + +## WriteBatch.set() + +Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. + +Signature: + +```typescript +set(documentRef: DocumentReference, data: PartialWithFieldValue, options: SetOptions): WriteBatch; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | +| data | [PartialWithFieldValue](./firestore_lite.md#partialwithfieldvalue)<T> | An object of the fields and values for the document. | +| options | [SetOptions](./firestore_lite.md#setoptions) | An object to configure the set behavior. | + +Returns: + +[WriteBatch](./firestore_lite.writebatch.md#writebatch_class) + +This `WriteBatch` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not a valid Firestore document. + +## WriteBatch.update() + +Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. + +Signature: + +```typescript +update(documentRef: DocumentReference, data: UpdateData): WriteBatch; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be updated. | +| data | [UpdateData](./firestore_lite.md#updatedata)<T> | An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document. | + +Returns: + +[WriteBatch](./firestore_lite.writebatch.md#writebatch_class) + +This `WriteBatch` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not valid Firestore data. + +## WriteBatch.update() + +Updates fields in the document referred to by this [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. + +Nested fields can be update by providing dot-separated field path strings or by providing `FieldPath` objects. + +Signature: + +```typescript +update(documentRef: DocumentReference, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): WriteBatch; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to the document to be updated. | +| field | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The first field to update. | +| value | unknown | The first value. | +| moreFieldsAndValues | unknown\[\] | Additional key value pairs. | + +Returns: + +[WriteBatch](./firestore_lite.writebatch.md#writebatch_class) + +This `WriteBatch` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not valid Firestore data. + diff --git a/docs-devsite/functions.functions.md b/docs-devsite/functions.functions.md new file mode 100644 index 00000000000..da5e0585f45 --- /dev/null +++ b/docs-devsite/functions.functions.md @@ -0,0 +1,57 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Functions interface +A `Functions` instance. + +Signature: + +```typescript +export interface Functions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [app](./functions.functions.md#functionsapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this Functions instance is associated with. | +| [customDomain](./functions.functions.md#functionscustomdomain) | string \| null | A custom domain hosting the callable Cloud Functions. ex: https://mydomain.com | +| [region](./functions.functions.md#functionsregion) | string | The region the callable Cloud Functions are located in. Default is us-central-1. | + +## Functions.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `Functions` instance is associated with. + +Signature: + +```typescript +app: FirebaseApp; +``` + +## Functions.customDomain + +A custom domain hosting the callable Cloud Functions. ex: https://mydomain.com + +Signature: + +```typescript +customDomain: string | null; +``` + +## Functions.region + +The region the callable Cloud Functions are located in. Default is `us-central-1`. + +Signature: + +```typescript +region: string; +``` diff --git a/docs-devsite/functions.functionserror.md b/docs-devsite/functions.functionserror.md new file mode 100644 index 00000000000..3be96745b4c --- /dev/null +++ b/docs-devsite/functions.functionserror.md @@ -0,0 +1,47 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FunctionsError interface +An error returned by the Firebase Functions client SDK. + +Signature: + +```typescript +export interface FunctionsError extends FirebaseError +``` +Extends: [FirebaseError](./util.firebaseerror.md#firebaseerror_class) + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [code](./functions.functionserror.md#functionserrorcode) | [FunctionsErrorCode](./functions.md#functionserrorcode) | A standard error code that will be returned to the client. This also determines the HTTP status code of the response, as defined in code.proto. | +| [details](./functions.functionserror.md#functionserrordetails) | unknown | Extra data to be converted to JSON and included in the error response. | + +## FunctionsError.code + +A standard error code that will be returned to the client. This also determines the HTTP status code of the response, as defined in code.proto. + +Signature: + +```typescript +readonly code: FunctionsErrorCode; +``` + +## FunctionsError.details + +Extra data to be converted to JSON and included in the error response. + +Signature: + +```typescript +readonly details?: unknown; +``` diff --git a/docs-devsite/functions.httpscallableoptions.md b/docs-devsite/functions.httpscallableoptions.md new file mode 100644 index 00000000000..cb84abf2526 --- /dev/null +++ b/docs-devsite/functions.httpscallableoptions.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# HttpsCallableOptions interface +An interface for metadata about how calls should be executed. + +Signature: + +```typescript +export interface HttpsCallableOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [timeout](./functions.httpscallableoptions.md#httpscallableoptionstimeout) | number | Time in milliseconds after which to cancel if there is no response. Default is 70000. | + +## HttpsCallableOptions.timeout + +Time in milliseconds after which to cancel if there is no response. Default is 70000. + +Signature: + +```typescript +timeout?: number; +``` diff --git a/docs-devsite/functions.httpscallableresult.md b/docs-devsite/functions.httpscallableresult.md new file mode 100644 index 00000000000..6c9877f423b --- /dev/null +++ b/docs-devsite/functions.httpscallableresult.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# HttpsCallableResult interface +An `HttpsCallableResult` wraps a single result from a function call. + +Signature: + +```typescript +export interface HttpsCallableResult +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [data](./functions.httpscallableresult.md#httpscallableresultdata) | ResponseData | Data returned from callable function. | + +## HttpsCallableResult.data + +Data returned from callable function. + +Signature: + +```typescript +readonly data: ResponseData; +``` diff --git a/docs-devsite/functions.md b/docs-devsite/functions.md new file mode 100644 index 00000000000..35b5087e08e --- /dev/null +++ b/docs-devsite/functions.md @@ -0,0 +1,162 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# functions package +Cloud Functions for Firebase + +## Functions + +| Function | Description | +| --- | --- | +| function(app...) | +| [getFunctions(app, regionOrCustomDomain)](./functions.md#getfunctions) | Returns a [Functions](./functions.functions.md#functions_interface) instance for the given app. | +| function(functionsInstance...) | +| [connectFunctionsEmulator(functionsInstance, host, port)](./functions.md#connectfunctionsemulator) | Modify this instance to communicate with the Cloud Functions emulator.Note: this must be called before this instance has been used to do any operations. | +| [httpsCallable(functionsInstance, name, options)](./functions.md#httpscallable) | Returns a reference to the callable HTTPS trigger with the given name. | +| [httpsCallableFromURL(functionsInstance, url, options)](./functions.md#httpscallablefromurl) | Returns a reference to the callable HTTPS trigger with the specified url. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [Functions](./functions.functions.md#functions_interface) | A Functions instance. | +| [FunctionsError](./functions.functionserror.md#functionserror_interface) | An error returned by the Firebase Functions client SDK. | +| [HttpsCallableOptions](./functions.httpscallableoptions.md#httpscallableoptions_interface) | An interface for metadata about how calls should be executed. | +| [HttpsCallableResult](./functions.httpscallableresult.md#httpscallableresult_interface) | An HttpsCallableResult wraps a single result from a function call. | + +## Type Aliases + +| Type Alias | Description | +| --- | --- | +| [FunctionsErrorCode](./functions.md#functionserrorcode) | The set of Firebase Functions status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.mdPossible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (e.g. an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation. | +| [FunctionsErrorCodeCore](./functions.md#functionserrorcodecore) | Functions error code string appended after "functions/" product prefix. See [FunctionsErrorCode](./functions.md#functionserrorcode) for full documentation of codes. | +| [HttpsCallable](./functions.md#httpscallable) | A reference to a "callable" HTTP trigger in Google Cloud Functions. | + +## getFunctions() + +Returns a [Functions](./functions.functions.md#functions_interface) instance for the given app. + +Signature: + +```typescript +export declare function getFunctions(app?: FirebaseApp, regionOrCustomDomain?: string): Functions; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to use. | +| regionOrCustomDomain | string | one of: a) The region the callable functions are located in (ex: us-central1) b) A custom domain hosting the callable functions (ex: https://mydomain.com) | + +Returns: + +[Functions](./functions.functions.md#functions_interface) + +## connectFunctionsEmulator() + +Modify this instance to communicate with the Cloud Functions emulator. + +Note: this must be called before this instance has been used to do any operations. + +Signature: + +```typescript +export declare function connectFunctionsEmulator(functionsInstance: Functions, host: string, port: number): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| functionsInstance | [Functions](./functions.functions.md#functions_interface) | | +| host | string | The emulator host (ex: localhost) | +| port | number | The emulator port (ex: 5001) | + +Returns: + +void + +## httpsCallable() + +Returns a reference to the callable HTTPS trigger with the given name. + +Signature: + +```typescript +export declare function httpsCallable(functionsInstance: Functions, name: string, options?: HttpsCallableOptions): HttpsCallable; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| functionsInstance | [Functions](./functions.functions.md#functions_interface) | | +| name | string | The name of the trigger. | +| options | [HttpsCallableOptions](./functions.httpscallableoptions.md#httpscallableoptions_interface) | | + +Returns: + +[HttpsCallable](./functions.md#httpscallable)<RequestData, ResponseData> + +## httpsCallableFromURL() + +Returns a reference to the callable HTTPS trigger with the specified url. + +Signature: + +```typescript +export declare function httpsCallableFromURL(functionsInstance: Functions, url: string, options?: HttpsCallableOptions): HttpsCallable; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| functionsInstance | [Functions](./functions.functions.md#functions_interface) | | +| url | string | The url of the trigger. | +| options | [HttpsCallableOptions](./functions.httpscallableoptions.md#httpscallableoptions_interface) | | + +Returns: + +[HttpsCallable](./functions.md#httpscallable)<RequestData, ResponseData> + +## FunctionsErrorCode + +The set of Firebase Functions status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.md + +Possible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (e.g. an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation. + +Signature: + +```typescript +export declare type FunctionsErrorCode = `functions/${FunctionsErrorCodeCore}`; +``` + +## FunctionsErrorCodeCore + +Functions error code string appended after "functions/" product prefix. See [FunctionsErrorCode](./functions.md#functionserrorcode) for full documentation of codes. + +Signature: + +```typescript +export declare type FunctionsErrorCodeCore = 'ok' | 'cancelled' | 'unknown' | 'invalid-argument' | 'deadline-exceeded' | 'not-found' | 'already-exists' | 'permission-denied' | 'resource-exhausted' | 'failed-precondition' | 'aborted' | 'out-of-range' | 'unimplemented' | 'internal' | 'unavailable' | 'data-loss' | 'unauthenticated'; +``` + +## HttpsCallable + +A reference to a "callable" HTTP trigger in Google Cloud Functions. + +Signature: + +```typescript +export declare type HttpsCallable = (data?: RequestData | null) => Promise>; +``` diff --git a/docs-devsite/index.md b/docs-devsite/index.md new file mode 100644 index 00000000000..e19f70906ef --- /dev/null +++ b/docs-devsite/index.md @@ -0,0 +1,30 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# API Reference + +## Packages + +| Package | Description | +| --- | --- | +| [@firebase/analytics](./analytics.md#analytics_package) | Firebase Analytics | +| [@firebase/app](./app.md#app_package) | Firebase App | +| [@firebase/app-check](./app-check.md#app-check_package) | Firebase App Check | +| [@firebase/auth](./auth.md#auth_package) | Firebase Authentication | +| [@firebase/database](./database.md#database_package) | Firebase Realtime Database | +| [@firebase/firestore](./firestore.md#firestore_package) | Cloud Firestore | +| [@firebase/functions](./functions.md#functions_package) | Cloud Functions for Firebase | +| [@firebase/installations](./installations.md#installations_package) | Firebase Installations | +| [@firebase/messaging](./messaging.md#messaging_package) | Firebase Cloud Messaging | +| [@firebase/performance](./performance.md#performance_package) | Firebase Performance Monitoring | +| [@firebase/remote-config](./remote-config.md#remote-config_package) | Firebase Remote Config | +| [@firebase/storage](./storage.md#storage_package) | Cloud Storage for Firebase | + diff --git a/docs-devsite/installations.installations.md b/docs-devsite/installations.installations.md new file mode 100644 index 00000000000..4c1107e0354 --- /dev/null +++ b/docs-devsite/installations.installations.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Installations interface +Public interface of the Firebase Installations SDK. + +Signature: + +```typescript +export interface Installations +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [app](./installations.installations.md#installationsapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this Installations instance is associated with. | + +## Installations.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `Installations` instance is associated with. + +Signature: + +```typescript +app: FirebaseApp; +``` diff --git a/docs-devsite/installations.md b/docs-devsite/installations.md new file mode 100644 index 00000000000..1ef8b80b00e --- /dev/null +++ b/docs-devsite/installations.md @@ -0,0 +1,162 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# installations package +Firebase Installations + +## Functions + +| Function | Description | +| --- | --- | +| function(app...) | +| [getInstallations(app)](./installations.md#getinstallations) | Returns an instance of [Installations](./installations.installations.md#installations_interface) associated with the given [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. | +| function(installations...) | +| [deleteInstallations(installations)](./installations.md#deleteinstallations) | Deletes the Firebase Installation and all associated data. | +| [getId(installations)](./installations.md#getid) | Creates a Firebase Installation if there isn't one for the app and returns the Installation ID. | +| [getToken(installations, forceRefresh)](./installations.md#gettoken) | Returns a Firebase Installations auth token, identifying the current Firebase Installation. | +| [onIdChange(installations, callback)](./installations.md#onidchange) | Sets a new callback that will get called when Installation ID changes. Returns an unsubscribe function that will remove the callback when called. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [Installations](./installations.installations.md#installations_interface) | Public interface of the Firebase Installations SDK. | + +## Type Aliases + +| Type Alias | Description | +| --- | --- | +| [IdChangeCallbackFn](./installations.md#idchangecallbackfn) | An user defined callback function that gets called when Installations ID changes. | +| [IdChangeUnsubscribeFn](./installations.md#idchangeunsubscribefn) | Unsubscribe a callback function previously added via [IdChangeCallbackFn](./installations.md#idchangecallbackfn). | + +## getInstallations() + +Returns an instance of [Installations](./installations.installations.md#installations_interface) associated with the given [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. + +Signature: + +```typescript +export declare function getInstallations(app?: FirebaseApp): Installations; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. | + +Returns: + +[Installations](./installations.installations.md#installations_interface) + +## deleteInstallations() + +Deletes the Firebase Installation and all associated data. + +Signature: + +```typescript +export declare function deleteInstallations(installations: Installations): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| installations | [Installations](./installations.installations.md#installations_interface) | The Installations instance. | + +Returns: + +Promise<void> + +## getId() + +Creates a Firebase Installation if there isn't one for the app and returns the Installation ID. + +Signature: + +```typescript +export declare function getId(installations: Installations): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| installations | [Installations](./installations.installations.md#installations_interface) | The Installations instance. | + +Returns: + +Promise<string> + +## getToken() + +Returns a Firebase Installations auth token, identifying the current Firebase Installation. + +Signature: + +```typescript +export declare function getToken(installations: Installations, forceRefresh?: boolean): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| installations | [Installations](./installations.installations.md#installations_interface) | The Installations instance. | +| forceRefresh | boolean | Force refresh regardless of token expiration. | + +Returns: + +Promise<string> + +## onIdChange() + +Sets a new callback that will get called when Installation ID changes. Returns an unsubscribe function that will remove the callback when called. + +Signature: + +```typescript +export declare function onIdChange(installations: Installations, callback: IdChangeCallbackFn): IdChangeUnsubscribeFn; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| installations | [Installations](./installations.installations.md#installations_interface) | The Installations instance. | +| callback | [IdChangeCallbackFn](./installations.md#idchangecallbackfn) | The callback function that is invoked when FID changes. | + +Returns: + +[IdChangeUnsubscribeFn](./installations.md#idchangeunsubscribefn) + +A function that can be called to unsubscribe. + +## IdChangeCallbackFn + +An user defined callback function that gets called when Installations ID changes. + +Signature: + +```typescript +export declare type IdChangeCallbackFn = (installationId: string) => void; +``` + +## IdChangeUnsubscribeFn + +Unsubscribe a callback function previously added via [IdChangeCallbackFn](./installations.md#idchangecallbackfn). + +Signature: + +```typescript +export declare type IdChangeUnsubscribeFn = () => void; +``` diff --git a/docs-devsite/messaging.md b/docs-devsite/messaging.md new file mode 100644 index 00000000000..ffbdd9ee3d8 --- /dev/null +++ b/docs-devsite/messaging.md @@ -0,0 +1,19 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# messaging package +Firebase Cloud Messaging + +| Entry Point | Description | +| --- | --- | +| [/](./messaging_.md#@firebase/messaging) | | +| [/sw](./messaging_sw.md#@firebase/messaging/sw) | | + diff --git a/docs-devsite/messaging_.fcmoptions.md b/docs-devsite/messaging_.fcmoptions.md new file mode 100644 index 00000000000..15f6123bae2 --- /dev/null +++ b/docs-devsite/messaging_.fcmoptions.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FcmOptions interface +Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) + +Signature: + +```typescript +export interface FcmOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [analyticsLabel](./messaging_.fcmoptions.md#fcmoptionsanalyticslabel) | string | The label associated with the message's analytics data. | +| [link](./messaging_.fcmoptions.md#fcmoptionslink) | string | The link to open when the user clicks on the notification. | + +## FcmOptions.analyticsLabel + +The label associated with the message's analytics data. + +Signature: + +```typescript +analyticsLabel?: string; +``` + +## FcmOptions.link + +The link to open when the user clicks on the notification. + +Signature: + +```typescript +link?: string; +``` diff --git a/docs-devsite/messaging_.gettokenoptions.md b/docs-devsite/messaging_.gettokenoptions.md new file mode 100644 index 00000000000..ed506fb5666 --- /dev/null +++ b/docs-devsite/messaging_.gettokenoptions.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# GetTokenOptions interface +Options for [getToken()](./messaging_.md#gettoken) + +Signature: + +```typescript +export interface GetTokenOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [serviceWorkerRegistration](./messaging_.gettokenoptions.md#gettokenoptionsserviceworkerregistration) | ServiceWorkerRegistration | The service worker registration for receiving push messaging. If the registration is not provided explicitly, you need to have a firebase-messaging-sw.js at your root location. See [Retrieve the current registration token](https://firebase.google.com/docs/cloud-messaging/js/client#retrieve-the-current-registration-token) for more details. | +| [vapidKey](./messaging_.gettokenoptions.md#gettokenoptionsvapidkey) | string | The public server key provided to push services. It is used to authenticate the push subscribers to receive push messages only from sending servers that hold the corresponding private key. If it is not provided, a default VAPID key is used. Note that some push services (Chrome Push Service) require a non-default VAPID key. Therefore, it is recommended to generate and import a VAPID key for your project with [Configure Web Credentials with FCM](https://firebase.google.com/docs/cloud-messaging/js/client#configure_web_credentials_with_fcm). See [The Web Push Protocol](https://developers.google.com/web/fundamentals/push-notifications/web-push-protocol) for details on web push services. | + +## GetTokenOptions.serviceWorkerRegistration + +The service worker registration for receiving push messaging. If the registration is not provided explicitly, you need to have a `firebase-messaging-sw.js` at your root location. See [Retrieve the current registration token](https://firebase.google.com/docs/cloud-messaging/js/client#retrieve-the-current-registration-token) for more details. + +Signature: + +```typescript +serviceWorkerRegistration?: ServiceWorkerRegistration; +``` + +## GetTokenOptions.vapidKey + +The public server key provided to push services. It is used to authenticate the push subscribers to receive push messages only from sending servers that hold the corresponding private key. If it is not provided, a default VAPID key is used. Note that some push services (Chrome Push Service) require a non-default VAPID key. Therefore, it is recommended to generate and import a VAPID key for your project with [Configure Web Credentials with FCM](https://firebase.google.com/docs/cloud-messaging/js/client#configure_web_credentials_with_fcm). See [The Web Push Protocol](https://developers.google.com/web/fundamentals/push-notifications/web-push-protocol) for details on web push services. + +Signature: + +```typescript +vapidKey?: string; +``` diff --git a/docs-devsite/messaging_.md b/docs-devsite/messaging_.md new file mode 100644 index 00000000000..ad04429ac94 --- /dev/null +++ b/docs-devsite/messaging_.md @@ -0,0 +1,143 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# @firebase/messaging + +## Functions + +| Function | Description | +| --- | --- | +| function(app...) | +| [getMessaging(app)](./messaging_.md#getmessaging) | Retrieves a Firebase Cloud Messaging instance. | +| function(messaging...) | +| [deleteToken(messaging)](./messaging_.md#deletetoken) | Deletes the registration token associated with this [Messaging](./messaging_.messaging.md#messaging_interface) instance and unsubscribes the [Messaging](./messaging_.messaging.md#messaging_interface) instance from the push subscription. | +| [getToken(messaging, options)](./messaging_.md#gettoken) | Subscribes the [Messaging](./messaging_.messaging.md#messaging_interface) instance to push notifications. Returns an Firebase Cloud Messaging registration token that can be used to send push messages to that [Messaging](./messaging_.messaging.md#messaging_interface) instance.If a notification permission isn't already granted, this method asks the user for permission. The returned promise rejects if the user does not allow the app to show notifications. | +| [onMessage(messaging, nextOrObserver)](./messaging_.md#onmessage) | When a push message is received and the user is currently on a page for your origin, the message is passed to the page and an onMessage() event is dispatched with the payload of the push message. | +| function() | +| [isSupported()](./messaging_.md#issupported) | Checks if all required APIs exist in the browser. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [FcmOptions](./messaging_.fcmoptions.md#fcmoptions_interface) | Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) | +| [GetTokenOptions](./messaging_.gettokenoptions.md#gettokenoptions_interface) | Options for [getToken()](./messaging_.md#gettoken) | +| [MessagePayload](./messaging_.messagepayload.md#messagepayload_interface) | Message payload that contains the notification payload that is represented with [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) and the data payload that contains an arbitrary number of key-value pairs sent by developers through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) | +| [Messaging](./messaging_.messaging.md#messaging_interface) | Public interface of the Firebase Cloud Messaging SDK. | +| [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) | Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) | + +## getMessaging() + +Retrieves a Firebase Cloud Messaging instance. + +Signature: + +```typescript +export declare function getMessagingInWindow(app?: FirebaseApp): Messaging; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | | + +Returns: + +[Messaging](./messaging_.messaging.md#messaging_interface) + +The Firebase Cloud Messaging instance associated with the provided firebase app. + +## deleteToken() + +Deletes the registration token associated with this [Messaging](./messaging_.messaging.md#messaging_interface) instance and unsubscribes the [Messaging](./messaging_.messaging.md#messaging_interface) instance from the push subscription. + +Signature: + +```typescript +export declare function deleteToken(messaging: Messaging): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| messaging | [Messaging](./messaging_.messaging.md#messaging_interface) | The [Messaging](./messaging_.messaging.md#messaging_interface) instance. | + +Returns: + +Promise<boolean> + +The promise resolves when the token has been successfully deleted. + +## getToken() + +Subscribes the [Messaging](./messaging_.messaging.md#messaging_interface) instance to push notifications. Returns an Firebase Cloud Messaging registration token that can be used to send push messages to that [Messaging](./messaging_.messaging.md#messaging_interface) instance. + +If a notification permission isn't already granted, this method asks the user for permission. The returned promise rejects if the user does not allow the app to show notifications. + +Signature: + +```typescript +export declare function getToken(messaging: Messaging, options?: GetTokenOptions): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| messaging | [Messaging](./messaging_.messaging.md#messaging_interface) | The [Messaging](./messaging_.messaging.md#messaging_interface) instance. | +| options | [GetTokenOptions](./messaging_.gettokenoptions.md#gettokenoptions_interface) | Provides an optional vapid key and an optinoal service worker registration | + +Returns: + +Promise<string> + +The promise resolves with an FCM registration token. + +## onMessage() + +When a push message is received and the user is currently on a page for your origin, the message is passed to the page and an `onMessage()` event is dispatched with the payload of the push message. + +Signature: + +```typescript +export declare function onMessage(messaging: Messaging, nextOrObserver: NextFn | Observer): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| messaging | [Messaging](./messaging_.messaging.md#messaging_interface) | The [Messaging](./messaging_.messaging.md#messaging_interface) instance. | +| nextOrObserver | [NextFn](./util.md#nextfn)<[MessagePayload](./messaging_.messagepayload.md#messagepayload_interface)> \| [Observer](./util.observer.md#observer_interface)<[MessagePayload](./messaging_.messagepayload.md#messagepayload_interface)> | This function, or observer object with next defined, is called when a message is received and the user is currently viewing your page. | + +Returns: + +[Unsubscribe](./util.md#unsubscribe) + +To stop listening for messages execute this returned function. + +## isSupported() + +Checks if all required APIs exist in the browser. + +Signature: + +```typescript +export declare function isWindowSupported(): Promise; +``` +Returns: + +Promise<boolean> + +a Promise that resolves to a boolean. + diff --git a/docs-devsite/messaging_.messagepayload.md b/docs-devsite/messaging_.messagepayload.md new file mode 100644 index 00000000000..1a944ebbc52 --- /dev/null +++ b/docs-devsite/messaging_.messagepayload.md @@ -0,0 +1,92 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# MessagePayload interface +Message payload that contains the notification payload that is represented with [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) and the data payload that contains an arbitrary number of key-value pairs sent by developers through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) + +Signature: + +```typescript +export interface MessagePayload +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [collapseKey](./messaging_.messagepayload.md#messagepayloadcollapsekey) | string | The collapse key of the message. See [Non-collapsible and collapsible messages](https://firebase.google.com/docs/cloud-messaging/concept-options#collapsible_and_non-collapsible_messages) | +| [data](./messaging_.messagepayload.md#messagepayloaddata) | { \[key: string\]: string; } | Arbitrary key/value payload. | +| [fcmOptions](./messaging_.messagepayload.md#messagepayloadfcmoptions) | [FcmOptions](./messaging_.fcmoptions.md#fcmoptions_interface) | Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) | +| [from](./messaging_.messagepayload.md#messagepayloadfrom) | string | The sender of this message. | +| [messageId](./messaging_.messagepayload.md#messagepayloadmessageid) | string | The message id of a message. | +| [notification](./messaging_.messagepayload.md#messagepayloadnotification) | [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) | Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) | + +## MessagePayload.collapseKey + +The collapse key of the message. See [Non-collapsible and collapsible messages](https://firebase.google.com/docs/cloud-messaging/concept-options#collapsible_and_non-collapsible_messages) + +Signature: + +```typescript +collapseKey: string; +``` + +## MessagePayload.data + +Arbitrary key/value payload. + +Signature: + +```typescript +data?: { + [key: string]: string; + }; +``` + +## MessagePayload.fcmOptions + +Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) + +Signature: + +```typescript +fcmOptions?: FcmOptions; +``` + +## MessagePayload.from + +The sender of this message. + +Signature: + +```typescript +from: string; +``` + +## MessagePayload.messageId + +The message id of a message. + +Signature: + +```typescript +messageId: string; +``` + +## MessagePayload.notification + +Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) + +Signature: + +```typescript +notification?: NotificationPayload; +``` diff --git a/docs-devsite/messaging_.messaging.md b/docs-devsite/messaging_.messaging.md new file mode 100644 index 00000000000..8d16b75467a --- /dev/null +++ b/docs-devsite/messaging_.messaging.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Messaging interface +Public interface of the Firebase Cloud Messaging SDK. + +Signature: + +```typescript +export interface Messaging +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [app](./messaging_.messaging.md#messagingapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this Messaging instance is associated with. | + +## Messaging.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `Messaging` instance is associated with. + +Signature: + +```typescript +app: FirebaseApp; +``` diff --git a/docs-devsite/messaging_.notificationpayload.md b/docs-devsite/messaging_.notificationpayload.md new file mode 100644 index 00000000000..5978a55b6bf --- /dev/null +++ b/docs-devsite/messaging_.notificationpayload.md @@ -0,0 +1,68 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# NotificationPayload interface +Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) + +Signature: + +```typescript +export interface NotificationPayload +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [body](./messaging_.notificationpayload.md#notificationpayloadbody) | string | The notification's body text. | +| [icon](./messaging_.notificationpayload.md#notificationpayloadicon) | string | The URL to use for the notification's icon. If you don't send this key in the request, FCM displays the launcher icon specified in your app manifest. | +| [image](./messaging_.notificationpayload.md#notificationpayloadimage) | string | The URL of an image that is downloaded on the device and displayed in the notification. | +| [title](./messaging_.notificationpayload.md#notificationpayloadtitle) | string | The notification's title. | + +## NotificationPayload.body + +The notification's body text. + +Signature: + +```typescript +body?: string; +``` + +## NotificationPayload.icon + +The URL to use for the notification's icon. If you don't send this key in the request, FCM displays the launcher icon specified in your app manifest. + +Signature: + +```typescript +icon?: string; +``` + +## NotificationPayload.image + +The URL of an image that is downloaded on the device and displayed in the notification. + +Signature: + +```typescript +image?: string; +``` + +## NotificationPayload.title + +The notification's title. + +Signature: + +```typescript +title?: string; +``` diff --git a/docs-devsite/messaging_sw.fcmoptions.md b/docs-devsite/messaging_sw.fcmoptions.md new file mode 100644 index 00000000000..55fdddaa0e3 --- /dev/null +++ b/docs-devsite/messaging_sw.fcmoptions.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FcmOptions interface +Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) + +Signature: + +```typescript +export interface FcmOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [analyticsLabel](./messaging_sw.fcmoptions.md#fcmoptionsanalyticslabel) | string | The label associated with the message's analytics data. | +| [link](./messaging_sw.fcmoptions.md#fcmoptionslink) | string | The link to open when the user clicks on the notification. | + +## FcmOptions.analyticsLabel + +The label associated with the message's analytics data. + +Signature: + +```typescript +analyticsLabel?: string; +``` + +## FcmOptions.link + +The link to open when the user clicks on the notification. + +Signature: + +```typescript +link?: string; +``` diff --git a/docs-devsite/messaging_sw.gettokenoptions.md b/docs-devsite/messaging_sw.gettokenoptions.md new file mode 100644 index 00000000000..5e724513a02 --- /dev/null +++ b/docs-devsite/messaging_sw.gettokenoptions.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# GetTokenOptions interface +Options for [getToken()](./messaging_.md#gettoken) + +Signature: + +```typescript +export interface GetTokenOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [serviceWorkerRegistration](./messaging_sw.gettokenoptions.md#gettokenoptionsserviceworkerregistration) | ServiceWorkerRegistration | The service worker registration for receiving push messaging. If the registration is not provided explicitly, you need to have a firebase-messaging-sw.js at your root location. See [Retrieve the current registration token](https://firebase.google.com/docs/cloud-messaging/js/client#retrieve-the-current-registration-token) for more details. | +| [vapidKey](./messaging_sw.gettokenoptions.md#gettokenoptionsvapidkey) | string | The public server key provided to push services. It is used to authenticate the push subscribers to receive push messages only from sending servers that hold the corresponding private key. If it is not provided, a default VAPID key is used. Note that some push services (Chrome Push Service) require a non-default VAPID key. Therefore, it is recommended to generate and import a VAPID key for your project with [Configure Web Credentials with FCM](https://firebase.google.com/docs/cloud-messaging/js/client#configure_web_credentials_with_fcm). See [The Web Push Protocol](https://developers.google.com/web/fundamentals/push-notifications/web-push-protocol) for details on web push services. | + +## GetTokenOptions.serviceWorkerRegistration + +The service worker registration for receiving push messaging. If the registration is not provided explicitly, you need to have a `firebase-messaging-sw.js` at your root location. See [Retrieve the current registration token](https://firebase.google.com/docs/cloud-messaging/js/client#retrieve-the-current-registration-token) for more details. + +Signature: + +```typescript +serviceWorkerRegistration?: ServiceWorkerRegistration; +``` + +## GetTokenOptions.vapidKey + +The public server key provided to push services. It is used to authenticate the push subscribers to receive push messages only from sending servers that hold the corresponding private key. If it is not provided, a default VAPID key is used. Note that some push services (Chrome Push Service) require a non-default VAPID key. Therefore, it is recommended to generate and import a VAPID key for your project with [Configure Web Credentials with FCM](https://firebase.google.com/docs/cloud-messaging/js/client#configure_web_credentials_with_fcm). See [The Web Push Protocol](https://developers.google.com/web/fundamentals/push-notifications/web-push-protocol) for details on web push services. + +Signature: + +```typescript +vapidKey?: string; +``` diff --git a/docs-devsite/messaging_sw.md b/docs-devsite/messaging_sw.md new file mode 100644 index 00000000000..0950fc61034 --- /dev/null +++ b/docs-devsite/messaging_sw.md @@ -0,0 +1,116 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# @firebase/messaging/sw + +## Functions + +| Function | Description | +| --- | --- | +| function(app...) | +| [getMessaging(app)](./messaging_sw.md#getmessaging) | Retrieves a Firebase Cloud Messaging instance. | +| function(messaging...) | +| [experimentalSetDeliveryMetricsExportedToBigQueryEnabled(messaging, enable)](./messaging_sw.md#experimentalsetdeliverymetricsexportedtobigqueryenabled) | Enables or disables Firebase Cloud Messaging message delivery metrics export to BigQuery. By default, message delivery metrics are not exported to BigQuery. Use this method to enable or disable the export at runtime. | +| [onBackgroundMessage(messaging, nextOrObserver)](./messaging_sw.md#onbackgroundmessage) | Called when a message is received while the app is in the background. An app is considered to be in the background if no active window is displayed. | +| function() | +| [isSupported()](./messaging_sw.md#issupported) | Checks whether all required APIs exist within SW Context | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [FcmOptions](./messaging_sw.fcmoptions.md#fcmoptions_interface) | Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) | +| [GetTokenOptions](./messaging_sw.gettokenoptions.md#gettokenoptions_interface) | Options for [getToken()](./messaging_.md#gettoken) | +| [MessagePayload](./messaging_sw.messagepayload.md#messagepayload_interface) | Message payload that contains the notification payload that is represented with [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) and the data payload that contains an arbitrary number of key-value pairs sent by developers through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) | +| [Messaging](./messaging_sw.messaging.md#messaging_interface) | Public interface of the Firebase Cloud Messaging SDK. | +| [NotificationPayload](./messaging_sw.notificationpayload.md#notificationpayload_interface) | Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) | + +## getMessaging() + +Retrieves a Firebase Cloud Messaging instance. + +Signature: + +```typescript +export declare function getMessagingInSw(app?: FirebaseApp): Messaging; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | | + +Returns: + +[Messaging](./messaging_.messaging.md#messaging_interface) + +The Firebase Cloud Messaging instance associated with the provided firebase app. + +## experimentalSetDeliveryMetricsExportedToBigQueryEnabled() + +Enables or disables Firebase Cloud Messaging message delivery metrics export to BigQuery. By default, message delivery metrics are not exported to BigQuery. Use this method to enable or disable the export at runtime. + +Signature: + +```typescript +export declare function experimentalSetDeliveryMetricsExportedToBigQueryEnabled(messaging: Messaging, enable: boolean): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| messaging | [Messaging](./messaging_.messaging.md#messaging_interface) | The FirebaseMessaging instance. | +| enable | boolean | Whether Firebase Cloud Messaging should export message delivery metrics to BigQuery. | + +Returns: + +void + +## onBackgroundMessage() + +Called when a message is received while the app is in the background. An app is considered to be in the background if no active window is displayed. + +Signature: + +```typescript +export declare function onBackgroundMessage(messaging: Messaging, nextOrObserver: NextFn | Observer): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| messaging | [Messaging](./messaging_.messaging.md#messaging_interface) | The [Messaging](./messaging_.messaging.md#messaging_interface) instance. | +| nextOrObserver | [NextFn](./util.md#nextfn)<[MessagePayload](./messaging_.messagepayload.md#messagepayload_interface)> \| [Observer](./util.observer.md#observer_interface)<[MessagePayload](./messaging_.messagepayload.md#messagepayload_interface)> | This function, or observer object with next defined, is called when a message is received and the app is currently in the background. | + +Returns: + +[Unsubscribe](./util.md#unsubscribe) + +To stop listening for messages execute this returned function + +## isSupported() + +Checks whether all required APIs exist within SW Context + +Signature: + +```typescript +export declare function isSwSupported(): Promise; +``` +Returns: + +Promise<boolean> + +a Promise that resolves to a boolean. + diff --git a/docs-devsite/messaging_sw.messagepayload.md b/docs-devsite/messaging_sw.messagepayload.md new file mode 100644 index 00000000000..2037bb0016d --- /dev/null +++ b/docs-devsite/messaging_sw.messagepayload.md @@ -0,0 +1,92 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# MessagePayload interface +Message payload that contains the notification payload that is represented with [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) and the data payload that contains an arbitrary number of key-value pairs sent by developers through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) + +Signature: + +```typescript +export interface MessagePayload +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [collapseKey](./messaging_sw.messagepayload.md#messagepayloadcollapsekey) | string | The collapse key of the message. See [Non-collapsible and collapsible messages](https://firebase.google.com/docs/cloud-messaging/concept-options#collapsible_and_non-collapsible_messages) | +| [data](./messaging_sw.messagepayload.md#messagepayloaddata) | { \[key: string\]: string; } | Arbitrary key/value payload. | +| [fcmOptions](./messaging_sw.messagepayload.md#messagepayloadfcmoptions) | [FcmOptions](./messaging_.fcmoptions.md#fcmoptions_interface) | Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) | +| [from](./messaging_sw.messagepayload.md#messagepayloadfrom) | string | The sender of this message. | +| [messageId](./messaging_sw.messagepayload.md#messagepayloadmessageid) | string | The message id of a message. | +| [notification](./messaging_sw.messagepayload.md#messagepayloadnotification) | [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) | Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) | + +## MessagePayload.collapseKey + +The collapse key of the message. See [Non-collapsible and collapsible messages](https://firebase.google.com/docs/cloud-messaging/concept-options#collapsible_and_non-collapsible_messages) + +Signature: + +```typescript +collapseKey: string; +``` + +## MessagePayload.data + +Arbitrary key/value payload. + +Signature: + +```typescript +data?: { + [key: string]: string; + }; +``` + +## MessagePayload.fcmOptions + +Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) + +Signature: + +```typescript +fcmOptions?: FcmOptions; +``` + +## MessagePayload.from + +The sender of this message. + +Signature: + +```typescript +from: string; +``` + +## MessagePayload.messageId + +The message id of a message. + +Signature: + +```typescript +messageId: string; +``` + +## MessagePayload.notification + +Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) + +Signature: + +```typescript +notification?: NotificationPayload; +``` diff --git a/docs-devsite/messaging_sw.messaging.md b/docs-devsite/messaging_sw.messaging.md new file mode 100644 index 00000000000..cfd15fe9aaf --- /dev/null +++ b/docs-devsite/messaging_sw.messaging.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Messaging interface +Public interface of the Firebase Cloud Messaging SDK. + +Signature: + +```typescript +export interface Messaging +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [app](./messaging_sw.messaging.md#messagingapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this Messaging instance is associated with. | + +## Messaging.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `Messaging` instance is associated with. + +Signature: + +```typescript +app: FirebaseApp; +``` diff --git a/docs-devsite/messaging_sw.notificationpayload.md b/docs-devsite/messaging_sw.notificationpayload.md new file mode 100644 index 00000000000..c49ecfdf123 --- /dev/null +++ b/docs-devsite/messaging_sw.notificationpayload.md @@ -0,0 +1,68 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# NotificationPayload interface +Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) + +Signature: + +```typescript +export interface NotificationPayload +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [body](./messaging_sw.notificationpayload.md#notificationpayloadbody) | string | The notification's body text. | +| [icon](./messaging_sw.notificationpayload.md#notificationpayloadicon) | string | The URL to use for the notification's icon. If you don't send this key in the request, FCM displays the launcher icon specified in your app manifest. | +| [image](./messaging_sw.notificationpayload.md#notificationpayloadimage) | string | The URL of an image that is downloaded on the device and displayed in the notification. | +| [title](./messaging_sw.notificationpayload.md#notificationpayloadtitle) | string | The notification's title. | + +## NotificationPayload.body + +The notification's body text. + +Signature: + +```typescript +body?: string; +``` + +## NotificationPayload.icon + +The URL to use for the notification's icon. If you don't send this key in the request, FCM displays the launcher icon specified in your app manifest. + +Signature: + +```typescript +icon?: string; +``` + +## NotificationPayload.image + +The URL of an image that is downloaded on the device and displayed in the notification. + +Signature: + +```typescript +image?: string; +``` + +## NotificationPayload.title + +The notification's title. + +Signature: + +```typescript +title?: string; +``` diff --git a/docs-devsite/performance.firebaseperformance.md b/docs-devsite/performance.firebaseperformance.md new file mode 100644 index 00000000000..d8aea429952 --- /dev/null +++ b/docs-devsite/performance.firebaseperformance.md @@ -0,0 +1,57 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FirebasePerformance interface +The Firebase Performance Monitoring service interface. + +Signature: + +```typescript +export interface FirebasePerformance +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [app](./performance.firebaseperformance.md#firebaseperformanceapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this FirebasePerformance instance is associated with. | +| [dataCollectionEnabled](./performance.firebaseperformance.md#firebaseperformancedatacollectionenabled) | boolean | Controls the logging of custom traces. | +| [instrumentationEnabled](./performance.firebaseperformance.md#firebaseperformanceinstrumentationenabled) | boolean | Controls the logging of automatic traces and HTTP/S network monitoring. | + +## FirebasePerformance.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `FirebasePerformance` instance is associated with. + +Signature: + +```typescript +app: FirebaseApp; +``` + +## FirebasePerformance.dataCollectionEnabled + +Controls the logging of custom traces. + +Signature: + +```typescript +dataCollectionEnabled: boolean; +``` + +## FirebasePerformance.instrumentationEnabled + +Controls the logging of automatic traces and HTTP/S network monitoring. + +Signature: + +```typescript +instrumentationEnabled: boolean; +``` diff --git a/docs-devsite/performance.md b/docs-devsite/performance.md new file mode 100644 index 00000000000..247002ed70a --- /dev/null +++ b/docs-devsite/performance.md @@ -0,0 +1,94 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# performance package +Firebase Performance Monitoring + +## Functions + +| Function | Description | +| --- | --- | +| function(app...) | +| [getPerformance(app)](./performance.md#getperformance) | Returns a [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) instance for the given app. | +| [initializePerformance(app, settings)](./performance.md#initializeperformance) | Returns a [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) instance for the given app. Can only be called once. | +| function(performance...) | +| [trace(performance, name)](./performance.md#trace) | Returns a new PerformanceTrace instance. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) | The Firebase Performance Monitoring service interface. | +| [PerformanceSettings](./performance.performancesettings.md#performancesettings_interface) | Defines configuration options for the Performance Monitoring SDK. | +| [PerformanceTrace](./performance.performancetrace.md#performancetrace_interface) | The interface representing a Trace. | + +## getPerformance() + +Returns a [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) instance for the given app. + +Signature: + +```typescript +export declare function getPerformance(app?: FirebaseApp): FirebasePerformance; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to use. | + +Returns: + +[FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) + +## initializePerformance() + +Returns a [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) instance for the given app. Can only be called once. + +Signature: + +```typescript +export declare function initializePerformance(app: FirebaseApp, settings?: PerformanceSettings): FirebasePerformance; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to use. | +| settings | [PerformanceSettings](./performance.performancesettings.md#performancesettings_interface) | Optional settings for the [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) instance. | + +Returns: + +[FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) + +## trace() + +Returns a new `PerformanceTrace` instance. + +Signature: + +```typescript +export declare function trace(performance: FirebasePerformance, name: string): PerformanceTrace; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| performance | [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) | The [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) instance to use. | +| name | string | The name of the trace. | + +Returns: + +[PerformanceTrace](./performance.performancetrace.md#performancetrace_interface) + diff --git a/docs-devsite/performance.performancesettings.md b/docs-devsite/performance.performancesettings.md new file mode 100644 index 00000000000..9d85a96ce6a --- /dev/null +++ b/docs-devsite/performance.performancesettings.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# PerformanceSettings interface +Defines configuration options for the Performance Monitoring SDK. + +Signature: + +```typescript +export interface PerformanceSettings +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [dataCollectionEnabled](./performance.performancesettings.md#performancesettingsdatacollectionenabled) | boolean | Whether to collect custom events. | +| [instrumentationEnabled](./performance.performancesettings.md#performancesettingsinstrumentationenabled) | boolean | Whether to collect out of the box events. | + +## PerformanceSettings.dataCollectionEnabled + +Whether to collect custom events. + +Signature: + +```typescript +dataCollectionEnabled?: boolean; +``` + +## PerformanceSettings.instrumentationEnabled + +Whether to collect out of the box events. + +Signature: + +```typescript +instrumentationEnabled?: boolean; +``` diff --git a/docs-devsite/performance.performancetrace.md b/docs-devsite/performance.performancetrace.md new file mode 100644 index 00000000000..ffda20476da --- /dev/null +++ b/docs-devsite/performance.performancetrace.md @@ -0,0 +1,228 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# PerformanceTrace interface +The interface representing a `Trace`. + +Signature: + +```typescript +export interface PerformanceTrace +``` + +## Methods + +| Method | Description | +| --- | --- | +| [getAttribute(attr)](./performance.performancetrace.md#performancetracegetattribute) | Retrieves the value which a custom attribute is set to. | +| [getAttributes()](./performance.performancetrace.md#performancetracegetattributes) | Returns a map of all custom attributes of a trace instance. | +| [getMetric(metricName)](./performance.performancetrace.md#performancetracegetmetric) | Returns the value of the custom metric by that name. If a custom metric with that name does not exist will return zero. | +| [incrementMetric(metricName, num)](./performance.performancetrace.md#performancetraceincrementmetric) | Adds to the value of a custom metric. If a custom metric with the provided name does not exist, it creates one with that name and the value equal to the given number. The value will be floored down to an integer. | +| [putAttribute(attr, value)](./performance.performancetrace.md#performancetraceputattribute) | Set a custom attribute of a trace to a certain value. | +| [putMetric(metricName, num)](./performance.performancetrace.md#performancetraceputmetric) | Sets the value of the specified custom metric to the given number regardless of whether a metric with that name already exists on the trace instance or not. The value will be floored down to an integer. | +| [record(startTime, duration, options)](./performance.performancetrace.md#performancetracerecord) | Records a trace from given parameters. This provides a direct way to use trace without a need to start/stop. This is useful for use cases in which the trace cannot directly be used (e.g. if the duration was captured before the Performance SDK was loaded). | +| [removeAttribute(attr)](./performance.performancetrace.md#performancetraceremoveattribute) | Removes the specified custom attribute from a trace instance. | +| [start()](./performance.performancetrace.md#performancetracestart) | Starts the timing for the trace instance. | +| [stop()](./performance.performancetrace.md#performancetracestop) | Stops the timing of the trace instance and logs the data of the instance. | + +## PerformanceTrace.getAttribute() + +Retrieves the value which a custom attribute is set to. + +Signature: + +```typescript +getAttribute(attr: string): string | undefined; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| attr | string | Name of the custom attribute. | + +Returns: + +string \| undefined + +## PerformanceTrace.getAttributes() + +Returns a map of all custom attributes of a trace instance. + +Signature: + +```typescript +getAttributes(): { + [key: string]: string; + }; +``` +Returns: + +{ \[key: string\]: string; } + +## PerformanceTrace.getMetric() + +Returns the value of the custom metric by that name. If a custom metric with that name does not exist will return zero. + +Signature: + +```typescript +getMetric(metricName: string): number; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| metricName | string | Name of the custom metric. | + +Returns: + +number + +## PerformanceTrace.incrementMetric() + +Adds to the value of a custom metric. If a custom metric with the provided name does not exist, it creates one with that name and the value equal to the given number. The value will be floored down to an integer. + +Signature: + +```typescript +incrementMetric(metricName: string, num?: number): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| metricName | string | The name of the custom metric. | +| num | number | The number to be added to the value of the custom metric. If not provided, it uses a default value of one. | + +Returns: + +void + +## PerformanceTrace.putAttribute() + +Set a custom attribute of a trace to a certain value. + +Signature: + +```typescript +putAttribute(attr: string, value: string): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| attr | string | Name of the custom attribute. | +| value | string | Value of the custom attribute. | + +Returns: + +void + +## PerformanceTrace.putMetric() + +Sets the value of the specified custom metric to the given number regardless of whether a metric with that name already exists on the trace instance or not. The value will be floored down to an integer. + +Signature: + +```typescript +putMetric(metricName: string, num: number): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| metricName | string | Name of the custom metric. | +| num | number | Value to of the custom metric. | + +Returns: + +void + +## PerformanceTrace.record() + +Records a trace from given parameters. This provides a direct way to use trace without a need to start/stop. This is useful for use cases in which the trace cannot directly be used (e.g. if the duration was captured before the Performance SDK was loaded). + +Signature: + +```typescript +record(startTime: number, duration: number, options?: { + metrics?: { + [key: string]: number; + }; + attributes?: { + [key: string]: string; + }; + }): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| startTime | number | trace start time since epoch in millisec. | +| duration | number | The duraction of the trace in millisec. | +| options | { metrics?: { \[key: string\]: number; }; attributes?: { \[key: string\]: string; }; } | An object which can optionally hold maps of custom metrics and custom attributes. | + +Returns: + +void + +## PerformanceTrace.removeAttribute() + +Removes the specified custom attribute from a trace instance. + +Signature: + +```typescript +removeAttribute(attr: string): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| attr | string | Name of the custom attribute. | + +Returns: + +void + +## PerformanceTrace.start() + +Starts the timing for the trace instance. + +Signature: + +```typescript +start(): void; +``` +Returns: + +void + +## PerformanceTrace.stop() + +Stops the timing of the trace instance and logs the data of the instance. + +Signature: + +```typescript +stop(): void; +``` +Returns: + +void + diff --git a/docs-devsite/remote-config.md b/docs-devsite/remote-config.md new file mode 100644 index 00000000000..5011c3b12b9 --- /dev/null +++ b/docs-devsite/remote-config.md @@ -0,0 +1,345 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# remote-config package +Firebase Remote Config + +## Functions + +| Function | Description | +| --- | --- | +| function(app...) | +| [getRemoteConfig(app)](./remote-config.md#getremoteconfig) | | +| function(remoteConfig...) | +| [activate(remoteConfig)](./remote-config.md#activate) | Makes the last fetched config available to the getters. | +| [ensureInitialized(remoteConfig)](./remote-config.md#ensureinitialized) | Ensures the last activated config are available to the getters. | +| [fetchAndActivate(remoteConfig)](./remote-config.md#fetchandactivate) | Performs fetch and activate operations, as a convenience. | +| [fetchConfig(remoteConfig)](./remote-config.md#fetchconfig) | Fetches and caches configuration from the Remote Config service. | +| [getAll(remoteConfig)](./remote-config.md#getall) | Gets all config. | +| [getBoolean(remoteConfig, key)](./remote-config.md#getboolean) | Gets the value for the given key as a boolean.Convenience method for calling remoteConfig.getValue(key).asBoolean(). | +| [getNumber(remoteConfig, key)](./remote-config.md#getnumber) | Gets the value for the given key as a number.Convenience method for calling remoteConfig.getValue(key).asNumber(). | +| [getString(remoteConfig, key)](./remote-config.md#getstring) | Gets the value for the given key as a string. Convenience method for calling remoteConfig.getValue(key).asString(). | +| [getValue(remoteConfig, key)](./remote-config.md#getvalue) | Gets the [Value](./remote-config.value.md#value_interface) for the given key. | +| [setLogLevel(remoteConfig, logLevel)](./remote-config.md#setloglevel) | Defines the log level to use. | +| function() | +| [isSupported()](./remote-config.md#issupported) | This method provides two different checks:1. Check if IndexedDB exists in the browser environment. 2. Check if the current browser context allows IndexedDB open() calls. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The Firebase Remote Config service interface. | +| [RemoteConfigSettings](./remote-config.remoteconfigsettings.md#remoteconfigsettings_interface) | Defines configuration options for the Remote Config SDK. | +| [Value](./remote-config.value.md#value_interface) | Wraps a value with metadata and type-safe getters. | + +## Type Aliases + +| Type Alias | Description | +| --- | --- | +| [FetchStatus](./remote-config.md#fetchstatus) | Summarizes the outcome of the last attempt to fetch config from the Firebase Remote Config server.
  • "no-fetch-yet" indicates the [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance has not yet attempted to fetch config, or that SDK initialization is incomplete.
  • "success" indicates the last attempt succeeded.
  • "failure" indicates the last attempt failed.
  • "throttle" indicates the last attempt was rate-limited.
| +| [LogLevel](./remote-config.md#loglevel) | Defines levels of Remote Config logging. | +| [ValueSource](./remote-config.md#valuesource) | Indicates the source of a value.
  • "static" indicates the value was defined by a static constant.
  • "default" indicates the value was defined by default config.
  • "remote" indicates the value was defined by fetched config.
| + +## getRemoteConfig() + +Signature: + +```typescript +export declare function getRemoteConfig(app?: FirebaseApp): RemoteConfig; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. | + +Returns: + +[RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) + +A [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. + +## activate() + +Makes the last fetched config available to the getters. + +Signature: + +```typescript +export declare function activate(remoteConfig: RemoteConfig): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | + +Returns: + +Promise<boolean> + +A `Promise` which resolves to true if the current call activated the fetched configs. If the fetched configs were already activated, the `Promise` will resolve to false. + +## ensureInitialized() + +Ensures the last activated config are available to the getters. + +Signature: + +```typescript +export declare function ensureInitialized(remoteConfig: RemoteConfig): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | + +Returns: + +Promise<void> + +A `Promise` that resolves when the last activated config is available to the getters. + +## fetchAndActivate() + +Performs fetch and activate operations, as a convenience. + +Signature: + +```typescript +export declare function fetchAndActivate(remoteConfig: RemoteConfig): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | + +Returns: + +Promise<boolean> + +A `Promise` which resolves to true if the current call activated the fetched configs. If the fetched configs were already activated, the `Promise` will resolve to false. + +## fetchConfig() + +Fetches and caches configuration from the Remote Config service. + +Signature: + +```typescript +export declare function fetchConfig(remoteConfig: RemoteConfig): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | + +Returns: + +Promise<void> + +## getAll() + +Gets all config. + +Signature: + +```typescript +export declare function getAll(remoteConfig: RemoteConfig): Record; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | + +Returns: + +Record<string, [Value](./remote-config.value.md#value_interface)> + +All config. + +## getBoolean() + +Gets the value for the given key as a boolean. + +Convenience method for calling remoteConfig.getValue(key).asBoolean(). + +Signature: + +```typescript +export declare function getBoolean(remoteConfig: RemoteConfig, key: string): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | +| key | string | The name of the parameter. | + +Returns: + +boolean + +The value for the given key as a boolean. + +## getNumber() + +Gets the value for the given key as a number. + +Convenience method for calling remoteConfig.getValue(key).asNumber(). + +Signature: + +```typescript +export declare function getNumber(remoteConfig: RemoteConfig, key: string): number; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | +| key | string | The name of the parameter. | + +Returns: + +number + +The value for the given key as a number. + +## getString() + +Gets the value for the given key as a string. Convenience method for calling remoteConfig.getValue(key).asString(). + +Signature: + +```typescript +export declare function getString(remoteConfig: RemoteConfig, key: string): string; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | +| key | string | The name of the parameter. | + +Returns: + +string + +The value for the given key as a string. + +## getValue() + +Gets the [Value](./remote-config.value.md#value_interface) for the given key. + +Signature: + +```typescript +export declare function getValue(remoteConfig: RemoteConfig, key: string): Value; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | +| key | string | The name of the parameter. | + +Returns: + +[Value](./remote-config.value.md#value_interface) + +The value for the given key. + +## setLogLevel() + +Defines the log level to use. + +Signature: + +```typescript +export declare function setLogLevel(remoteConfig: RemoteConfig, logLevel: RemoteConfigLogLevel): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | +| logLevel | [RemoteConfigLogLevel](./remote-config.md#loglevel) | The log level to set. | + +Returns: + +void + +## isSupported() + +This method provides two different checks: + +1. Check if IndexedDB exists in the browser environment. 2. Check if the current browser context allows IndexedDB `open()` calls. + +Signature: + +```typescript +export declare function isSupported(): Promise; +``` +Returns: + +Promise<boolean> + +A `Promise` which resolves to true if a [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance can be initialized in this environment, or false if it cannot. + +## FetchStatus + +Summarizes the outcome of the last attempt to fetch config from the Firebase Remote Config server. + +
  • "no-fetch-yet" indicates the [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance has not yet attempted to fetch config, or that SDK initialization is incomplete.
  • "success" indicates the last attempt succeeded.
  • "failure" indicates the last attempt failed.
  • "throttle" indicates the last attempt was rate-limited.
+ +Signature: + +```typescript +export declare type FetchStatus = 'no-fetch-yet' | 'success' | 'failure' | 'throttle'; +``` + +## LogLevel + +Defines levels of Remote Config logging. + +Signature: + +```typescript +export declare type LogLevel = 'debug' | 'error' | 'silent'; +``` + +## ValueSource + +Indicates the source of a value. + +
  • "static" indicates the value was defined by a static constant.
  • "default" indicates the value was defined by default config.
  • "remote" indicates the value was defined by fetched config.
+ +Signature: + +```typescript +export declare type ValueSource = 'static' | 'default' | 'remote'; +``` diff --git a/docs-devsite/remote-config.remoteconfig.md b/docs-devsite/remote-config.remoteconfig.md new file mode 100644 index 00000000000..3f4f0688b13 --- /dev/null +++ b/docs-devsite/remote-config.remoteconfig.md @@ -0,0 +1,81 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# RemoteConfig interface +The Firebase Remote Config service interface. + +Signature: + +```typescript +export interface RemoteConfig +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [app](./remote-config.remoteconfig.md#remoteconfigapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this RemoteConfig instance is associated with. | +| [defaultConfig](./remote-config.remoteconfig.md#remoteconfigdefaultconfig) | { \[key: string\]: string \| number \| boolean; } | Object containing default values for configs. | +| [fetchTimeMillis](./remote-config.remoteconfig.md#remoteconfigfetchtimemillis) | number | The Unix timestamp in milliseconds of the last successful fetch, or negative one if the [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance either hasn't fetched or initialization is incomplete. | +| [lastFetchStatus](./remote-config.remoteconfig.md#remoteconfiglastfetchstatus) | [FetchStatus](./remote-config.md#fetchstatus) | The status of the last fetch attempt. | +| [settings](./remote-config.remoteconfig.md#remoteconfigsettings) | [RemoteConfigSettings](./remote-config.remoteconfigsettings.md#remoteconfigsettings_interface) | Defines configuration for the Remote Config SDK. | + +## RemoteConfig.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `RemoteConfig` instance is associated with. + +Signature: + +```typescript +app: FirebaseApp; +``` + +## RemoteConfig.defaultConfig + +Object containing default values for configs. + +Signature: + +```typescript +defaultConfig: { + [key: string]: string | number | boolean; + }; +``` + +## RemoteConfig.fetchTimeMillis + +The Unix timestamp in milliseconds of the last successful fetch, or negative one if the [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance either hasn't fetched or initialization is incomplete. + +Signature: + +```typescript +fetchTimeMillis: number; +``` + +## RemoteConfig.lastFetchStatus + +The status of the last fetch attempt. + +Signature: + +```typescript +lastFetchStatus: FetchStatus; +``` + +## RemoteConfig.settings + +Defines configuration for the Remote Config SDK. + +Signature: + +```typescript +settings: RemoteConfigSettings; +``` diff --git a/docs-devsite/remote-config.remoteconfigsettings.md b/docs-devsite/remote-config.remoteconfigsettings.md new file mode 100644 index 00000000000..58e505ad863 --- /dev/null +++ b/docs-devsite/remote-config.remoteconfigsettings.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# RemoteConfigSettings interface +Defines configuration options for the Remote Config SDK. + +Signature: + +```typescript +export interface RemoteConfigSettings +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [fetchTimeoutMillis](./remote-config.remoteconfigsettings.md#remoteconfigsettingsfetchtimeoutmillis) | number | Defines the maximum amount of milliseconds to wait for a response when fetching configuration from the Remote Config server. Defaults to 60000 (One minute). | +| [minimumFetchIntervalMillis](./remote-config.remoteconfigsettings.md#remoteconfigsettingsminimumfetchintervalmillis) | number | Defines the maximum age in milliseconds of an entry in the config cache before it is considered stale. Defaults to 43200000 (Twelve hours). | + +## RemoteConfigSettings.fetchTimeoutMillis + +Defines the maximum amount of milliseconds to wait for a response when fetching configuration from the Remote Config server. Defaults to 60000 (One minute). + +Signature: + +```typescript +fetchTimeoutMillis: number; +``` + +## RemoteConfigSettings.minimumFetchIntervalMillis + +Defines the maximum age in milliseconds of an entry in the config cache before it is considered stale. Defaults to 43200000 (Twelve hours). + +Signature: + +```typescript +minimumFetchIntervalMillis: number; +``` diff --git a/docs-devsite/remote-config.value.md b/docs-devsite/remote-config.value.md new file mode 100644 index 00000000000..36fb492d524 --- /dev/null +++ b/docs-devsite/remote-config.value.md @@ -0,0 +1,83 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Value interface +Wraps a value with metadata and type-safe getters. + +Signature: + +```typescript +export interface Value +``` + +## Methods + +| Method | Description | +| --- | --- | +| [asBoolean()](./remote-config.value.md#valueasboolean) | Gets the value as a boolean.The following values (case insensitive) are interpreted as true: "1", "true", "t", "yes", "y", "on". Other values are interpreted as false. | +| [asNumber()](./remote-config.value.md#valueasnumber) | Gets the value as a number. Comparable to calling Number(value) \|\| 0. | +| [asString()](./remote-config.value.md#valueasstring) | Gets the value as a string. | +| [getSource()](./remote-config.value.md#valuegetsource) | Gets the [ValueSource](./remote-config.md#valuesource) for the given key. | + +## Value.asBoolean() + +Gets the value as a boolean. + +The following values (case insensitive) are interpreted as true: "1", "true", "t", "yes", "y", "on". Other values are interpreted as false. + +Signature: + +```typescript +asBoolean(): boolean; +``` +Returns: + +boolean + +## Value.asNumber() + +Gets the value as a number. Comparable to calling Number(value) \|\| 0. + +Signature: + +```typescript +asNumber(): number; +``` +Returns: + +number + +## Value.asString() + +Gets the value as a string. + +Signature: + +```typescript +asString(): string; +``` +Returns: + +string + +## Value.getSource() + +Gets the [ValueSource](./remote-config.md#valuesource) for the given key. + +Signature: + +```typescript +getSource(): ValueSource; +``` +Returns: + +[ValueSource](./remote-config.md#valuesource) + diff --git a/docs-devsite/storage.firebasestorage.md b/docs-devsite/storage.firebasestorage.md new file mode 100644 index 00000000000..a44df8bfc3d --- /dev/null +++ b/docs-devsite/storage.firebasestorage.md @@ -0,0 +1,58 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FirebaseStorage interface +A Firebase Storage instance. + +Signature: + +```typescript +export interface FirebaseStorage extends _FirebaseService +``` +Extends: \_FirebaseService + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [app](./storage.firebasestorage.md#firebasestorageapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this FirebaseStorage instance. | +| [maxOperationRetryTime](./storage.firebasestorage.md#firebasestoragemaxoperationretrytime) | number | The maximum time to retry operations other than uploads or downloads in milliseconds. | +| [maxUploadRetryTime](./storage.firebasestorage.md#firebasestoragemaxuploadretrytime) | number | The maximum time to retry uploads in milliseconds. | + +## FirebaseStorage.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this `FirebaseStorage` instance. + +Signature: + +```typescript +readonly app: FirebaseApp; +``` + +## FirebaseStorage.maxOperationRetryTime + +The maximum time to retry operations other than uploads or downloads in milliseconds. + +Signature: + +```typescript +maxOperationRetryTime: number; +``` + +## FirebaseStorage.maxUploadRetryTime + +The maximum time to retry uploads in milliseconds. + +Signature: + +```typescript +maxUploadRetryTime: number; +``` diff --git a/docs-devsite/storage.fullmetadata.md b/docs-devsite/storage.fullmetadata.md new file mode 100644 index 00000000000..ca8d66e08d5 --- /dev/null +++ b/docs-devsite/storage.fullmetadata.md @@ -0,0 +1,135 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FullMetadata interface +The full set of object metadata, including read-only properties. + +Signature: + +```typescript +export interface FullMetadata extends UploadMetadata +``` +Extends: [UploadMetadata](./storage.uploadmetadata.md#uploadmetadata_interface) + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [bucket](./storage.fullmetadata.md#fullmetadatabucket) | string | The bucket this object is contained in. | +| [downloadTokens](./storage.fullmetadata.md#fullmetadatadownloadtokens) | string\[\] \| undefined | Tokens to allow access to the downloatd URL. | +| [fullPath](./storage.fullmetadata.md#fullmetadatafullpath) | string | The full path of this object. | +| [generation](./storage.fullmetadata.md#fullmetadatageneration) | string | The object's generation. [https://cloud.google.com/storage/docs/metadata\#generation-number](https://cloud.google.com/storage/docs/metadata#generation-number) | +| [metageneration](./storage.fullmetadata.md#fullmetadatametageneration) | string | The object's metageneration. [https://cloud.google.com/storage/docs/metadata\#generation-number](https://cloud.google.com/storage/docs/metadata#generation-number) | +| [name](./storage.fullmetadata.md#fullmetadataname) | string | The short name of this object, which is the last component of the full path. For example, if fullPath is 'full/path/image.png', name is 'image.png'. | +| [ref](./storage.fullmetadata.md#fullmetadataref) | [StorageReference](./storage.storagereference.md#storagereference_interface) \| undefined | StorageReference associated with this upload. | +| [size](./storage.fullmetadata.md#fullmetadatasize) | number | The size of this object, in bytes. | +| [timeCreated](./storage.fullmetadata.md#fullmetadatatimecreated) | string | A date string representing when this object was created. | +| [updated](./storage.fullmetadata.md#fullmetadataupdated) | string | A date string representing when this object was last updated. | + +## FullMetadata.bucket + +The bucket this object is contained in. + +Signature: + +```typescript +bucket: string; +``` + +## FullMetadata.downloadTokens + +Tokens to allow access to the downloatd URL. + +Signature: + +```typescript +downloadTokens: string[] | undefined; +``` + +## FullMetadata.fullPath + +The full path of this object. + +Signature: + +```typescript +fullPath: string; +``` + +## FullMetadata.generation + +The object's generation. [https://cloud.google.com/storage/docs/metadata\#generation-number](https://cloud.google.com/storage/docs/metadata#generation-number) + +Signature: + +```typescript +generation: string; +``` + +## FullMetadata.metageneration + +The object's metageneration. [https://cloud.google.com/storage/docs/metadata\#generation-number](https://cloud.google.com/storage/docs/metadata#generation-number) + +Signature: + +```typescript +metageneration: string; +``` + +## FullMetadata.name + +The short name of this object, which is the last component of the full path. For example, if fullPath is 'full/path/image.png', name is 'image.png'. + +Signature: + +```typescript +name: string; +``` + +## FullMetadata.ref + +`StorageReference` associated with this upload. + +Signature: + +```typescript +ref?: StorageReference | undefined; +``` + +## FullMetadata.size + +The size of this object, in bytes. + +Signature: + +```typescript +size: number; +``` + +## FullMetadata.timeCreated + +A date string representing when this object was created. + +Signature: + +```typescript +timeCreated: string; +``` + +## FullMetadata.updated + +A date string representing when this object was last updated. + +Signature: + +```typescript +updated: string; +``` diff --git a/docs-devsite/storage.listoptions.md b/docs-devsite/storage.listoptions.md new file mode 100644 index 00000000000..3f2e92bc639 --- /dev/null +++ b/docs-devsite/storage.listoptions.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ListOptions interface +The options `list()` accepts. + +Signature: + +```typescript +export interface ListOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [maxResults](./storage.listoptions.md#listoptionsmaxresults) | number \| null | If set, limits the total number of prefixes and items to return. The default and maximum maxResults is 1000. | +| [pageToken](./storage.listoptions.md#listoptionspagetoken) | string \| null | The nextPageToken from a previous call to list(). If provided, listing is resumed from the previous position. | + +## ListOptions.maxResults + +If set, limits the total number of `prefixes` and `items` to return. The default and maximum maxResults is 1000. + +Signature: + +```typescript +maxResults?: number | null; +``` + +## ListOptions.pageToken + +The `nextPageToken` from a previous call to `list()`. If provided, listing is resumed from the previous position. + +Signature: + +```typescript +pageToken?: string | null; +``` diff --git a/docs-devsite/storage.listresult.md b/docs-devsite/storage.listresult.md new file mode 100644 index 00000000000..b53a61d92db --- /dev/null +++ b/docs-devsite/storage.listresult.md @@ -0,0 +1,59 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ListResult interface +Result returned by list(). + +Signature: + +```typescript +export interface ListResult +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [items](./storage.listresult.md#listresultitems) | [StorageReference](./storage.storagereference.md#storagereference_interface)\[\] | Objects in this directory. You can call getMetadata() and getDownloadUrl() on them. | +| [nextPageToken](./storage.listresult.md#listresultnextpagetoken) | string | If set, there might be more results for this list. Use this token to resume the list. | +| [prefixes](./storage.listresult.md#listresultprefixes) | [StorageReference](./storage.storagereference.md#storagereference_interface)\[\] | References to prefixes (sub-folders). You can call list() on them to get its contents.Folders are implicit based on '/' in the object paths. For example, if a bucket has two objects '/a/b/1' and '/a/b/2', list('/a') will return '/a/b' as a prefix. | + +## ListResult.items + +Objects in this directory. You can call getMetadata() and getDownloadUrl() on them. + +Signature: + +```typescript +items: StorageReference[]; +``` + +## ListResult.nextPageToken + +If set, there might be more results for this list. Use this token to resume the list. + +Signature: + +```typescript +nextPageToken?: string; +``` + +## ListResult.prefixes + +References to prefixes (sub-folders). You can call list() on them to get its contents. + +Folders are implicit based on '/' in the object paths. For example, if a bucket has two objects '/a/b/1' and '/a/b/2', list('/a') will return '/a/b' as a prefix. + +Signature: + +```typescript +prefixes: StorageReference[]; +``` diff --git a/docs-devsite/storage.md b/docs-devsite/storage.md new file mode 100644 index 00000000000..0aab0c6a35d --- /dev/null +++ b/docs-devsite/storage.md @@ -0,0 +1,550 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# storage package +Cloud Storage for Firebase + +## Functions + +| Function | Description | +| --- | --- | +| function(app...) | +| [getStorage(app, bucketUrl)](./storage.md#getstorage) | Gets a [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance for the given Firebase app. | +| function(storage...) | +| [connectStorageEmulator(storage, host, port, options)](./storage.md#connectstorageemulator) | Modify this [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance to communicate with the Cloud Storage emulator. | +| [ref(storage, url)](./storage.md#ref) | Returns a [StorageReference](./storage.storagereference.md#storagereference_interface) for the given url. | +| function(ref...) | +| [deleteObject(ref)](./storage.md#deleteobject) | Deletes the object at this location. | +| [getBlob(ref, maxDownloadSizeBytes)](./storage.md#getblob) | Downloads the data at the object's location. Returns an error if the object is not found.To use this functionality, you have to whitelist your app's origin in your Cloud Storage bucket. See also https://cloud.google.com/storage/docs/configuring-corsThis API is not available in Node. | +| [getBytes(ref, maxDownloadSizeBytes)](./storage.md#getbytes) | Downloads the data at the object's location. Returns an error if the object is not found.To use this functionality, you have to whitelist your app's origin in your Cloud Storage bucket. See also https://cloud.google.com/storage/docs/configuring-cors | +| [getDownloadURL(ref)](./storage.md#getdownloadurl) | Returns the download URL for the given [StorageReference](./storage.storagereference.md#storagereference_interface). | +| [getMetadata(ref)](./storage.md#getmetadata) | A Promise that resolves with the metadata for this object. If this object doesn't exist or metadata cannot be retreived, the promise is rejected. | +| [getStream(ref, maxDownloadSizeBytes)](./storage.md#getstream) | Downloads the data at the object's location. Raises an error event if the object is not found.This API is only available in Node. | +| [list(ref, options)](./storage.md#list) | List items (files) and prefixes (folders) under this storage reference.List API is only available for Firebase Rules Version 2.GCS is a key-blob store. Firebase Storage imposes the semantic of '/' delimited folder structure. Refer to GCS's List API if you want to learn more.To adhere to Firebase Rules's Semantics, Firebase Storage does not support objects whose paths end with "/" or contain two consecutive "/"s. Firebase Storage List API will filter these unsupported objects. list() may fail if there are too many unsupported objects in the bucket. | +| [listAll(ref)](./storage.md#listall) | List all items (files) and prefixes (folders) under this storage reference.This is a helper method for calling list() repeatedly until there are no more results. The default pagination size is 1000.Note: The results may not be consistent if objects are changed while this operation is running.Warning: listAll may potentially consume too many resources if there are too many results. | +| [updateMetadata(ref, metadata)](./storage.md#updatemetadata) | Updates the metadata for this object. | +| [uploadBytes(ref, data, metadata)](./storage.md#uploadbytes) | Uploads data to this object's location. The upload is not resumable. | +| [uploadBytesResumable(ref, data, metadata)](./storage.md#uploadbytesresumable) | Uploads data to this object's location. The upload can be paused and resumed, and exposes progress updates. | +| [uploadString(ref, value, format, metadata)](./storage.md#uploadstring) | Uploads a string to this object's location. The upload is not resumable. | +| function(storageOrRef...) | +| [ref(storageOrRef, path)](./storage.md#ref) | Returns a [StorageReference](./storage.storagereference.md#storagereference_interface) for the given path in the default bucket. | + +## Classes + +| Class | Description | +| --- | --- | +| [StorageError](./storage.storageerror.md#storageerror_class) | An error returned by the Firebase Storage SDK. | + +## Enumerations + +| Enumeration | Description | +| --- | --- | +| [StorageErrorCode](./storage.md#storageerrorcode) | Error codes that can be attached to StorageError objects. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) | A Firebase Storage instance. | +| [FullMetadata](./storage.fullmetadata.md#fullmetadata_interface) | The full set of object metadata, including read-only properties. | +| [ListOptions](./storage.listoptions.md#listoptions_interface) | The options list() accepts. | +| [ListResult](./storage.listresult.md#listresult_interface) | Result returned by list(). | +| [SettableMetadata](./storage.settablemetadata.md#settablemetadata_interface) | Object metadata that can be set at any time. | +| [StorageObserver](./storage.storageobserver.md#storageobserver_interface) | A stream observer for Firebase Storage. | +| [StorageReference](./storage.storagereference.md#storagereference_interface) | Represents a reference to a Google Cloud Storage object. Developers can upload, download, and delete objects, as well as get/set object metadata. | +| [UploadMetadata](./storage.uploadmetadata.md#uploadmetadata_interface) | Object metadata that can be set at upload. | +| [UploadResult](./storage.uploadresult.md#uploadresult_interface) | Result returned from a non-resumable upload. | +| [UploadTask](./storage.uploadtask.md#uploadtask_interface) | Represents the process of uploading an object. Allows you to monitor and manage the upload. | +| [UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface) | Holds data about the current state of the upload task. | + +## Variables + +| Variable | Description | +| --- | --- | +| [StringFormat](./storage.md#stringformat) | An enumeration of the possible string formats for upload. | + +## Type Aliases + +| Type Alias | Description | +| --- | --- | +| [StringFormat](./storage.md#stringformat) | An enumeration of the possible string formats for upload. | +| [TaskEvent](./storage.md#taskevent) | An event that is triggered on a task. | +| [TaskState](./storage.md#taskstate) | Represents the current state of a running upload. | + +## getStorage() + +Gets a [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance for the given Firebase app. + +Signature: + +```typescript +export declare function getStorage(app?: FirebaseApp, bucketUrl?: string): FirebaseStorage; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | Firebase app to get [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance for. | +| bucketUrl | string | The gs:// url to your Firebase Storage Bucket. If not passed, uses the app's default Storage Bucket. | + +Returns: + +[FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) + +A [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance. + +## connectStorageEmulator() + +Modify this [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance to communicate with the Cloud Storage emulator. + +Signature: + +```typescript +export declare function connectStorageEmulator(storage: FirebaseStorage, host: string, port: number, options?: { + mockUserToken?: EmulatorMockTokenOptions | string; +}): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| storage | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) | The [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance | +| host | string | The emulator host (ex: localhost) | +| port | number | The emulator port (ex: 5001) | +| options | { mockUserToken?: [EmulatorMockTokenOptions](./util.md#emulatormocktokenoptions) \| string; } | Emulator options. options.mockUserToken is the mock auth token to use for unit testing Security Rules. | + +Returns: + +void + +## ref() + +Returns a [StorageReference](./storage.storagereference.md#storagereference_interface) for the given url. + +Signature: + +```typescript +export declare function ref(storage: FirebaseStorage, url?: string): StorageReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| storage | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance. | +| url | string | URL. If empty, returns root reference. | + +Returns: + +[StorageReference](./storage.storagereference.md#storagereference_interface) + +## deleteObject() + +Deletes the object at this location. + +Signature: + +```typescript +export declare function deleteObject(ref: StorageReference): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) for object to delete. | + +Returns: + +Promise<void> + +A `Promise` that resolves if the deletion succeeds. + +## getBlob() + +Downloads the data at the object's location. Returns an error if the object is not found. + +To use this functionality, you have to whitelist your app's origin in your Cloud Storage bucket. See also https://cloud.google.com/storage/docs/configuring-cors + +This API is not available in Node. + +Signature: + +```typescript +export declare function getBlob(ref: StorageReference, maxDownloadSizeBytes?: number): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | StorageReference where data should be downloaded. | +| maxDownloadSizeBytes | number | If set, the maximum allowed size in bytes to retrieve. | + +Returns: + +Promise<Blob> + +A Promise that resolves with a Blob containing the object's bytes + +## getBytes() + +Downloads the data at the object's location. Returns an error if the object is not found. + +To use this functionality, you have to whitelist your app's origin in your Cloud Storage bucket. See also https://cloud.google.com/storage/docs/configuring-cors + +Signature: + +```typescript +export declare function getBytes(ref: StorageReference, maxDownloadSizeBytes?: number): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | StorageReference where data should be downloaded. | +| maxDownloadSizeBytes | number | If set, the maximum allowed size in bytes to retrieve. | + +Returns: + +Promise<ArrayBuffer> + +A Promise containing the object's bytes + +## getDownloadURL() + +Returns the download URL for the given [StorageReference](./storage.storagereference.md#storagereference_interface). + +Signature: + +```typescript +export declare function getDownloadURL(ref: StorageReference): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) to get the download URL for. | + +Returns: + +Promise<string> + +A `Promise` that resolves with the download URL for this object. + +## getMetadata() + +A `Promise` that resolves with the metadata for this object. If this object doesn't exist or metadata cannot be retreived, the promise is rejected. + +Signature: + +```typescript +export declare function getMetadata(ref: StorageReference): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) to get metadata from. | + +Returns: + +Promise<[FullMetadata](./storage.fullmetadata.md#fullmetadata_interface)> + +## getStream() + +Downloads the data at the object's location. Raises an error event if the object is not found. + +This API is only available in Node. + +Signature: + +```typescript +export declare function getStream(ref: StorageReference, maxDownloadSizeBytes?: number): NodeJS.ReadableStream; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | StorageReference where data should be downloaded. | +| maxDownloadSizeBytes | number | If set, the maximum allowed size in bytes to retrieve. | + +Returns: + +NodeJS.ReadableStream + +A stream with the object's data as bytes + +## list() + +List items (files) and prefixes (folders) under this storage reference. + +List API is only available for Firebase Rules Version 2. + +GCS is a key-blob store. Firebase Storage imposes the semantic of '/' delimited folder structure. Refer to GCS's List API if you want to learn more. + +To adhere to Firebase Rules's Semantics, Firebase Storage does not support objects whose paths end with "/" or contain two consecutive "/"s. Firebase Storage List API will filter these unsupported objects. list() may fail if there are too many unsupported objects in the bucket. + +Signature: + +```typescript +export declare function list(ref: StorageReference, options?: ListOptions): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) to get list from. | +| options | [ListOptions](./storage.listoptions.md#listoptions_interface) | See [ListOptions](./storage.listoptions.md#listoptions_interface) for details. | + +Returns: + +Promise<[ListResult](./storage.listresult.md#listresult_interface)> + +A `Promise` that resolves with the items and prefixes. `prefixes` contains references to sub-folders and `items` contains references to objects in this folder. `nextPageToken` can be used to get the rest of the results. + +## listAll() + +List all items (files) and prefixes (folders) under this storage reference. + +This is a helper method for calling list() repeatedly until there are no more results. The default pagination size is 1000. + +Note: The results may not be consistent if objects are changed while this operation is running. + +Warning: `listAll` may potentially consume too many resources if there are too many results. + +Signature: + +```typescript +export declare function listAll(ref: StorageReference): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) to get list from. | + +Returns: + +Promise<[ListResult](./storage.listresult.md#listresult_interface)> + +A `Promise` that resolves with all the items and prefixes under the current storage reference. `prefixes` contains references to sub-directories and `items` contains references to objects in this folder. `nextPageToken` is never returned. + +## updateMetadata() + +Updates the metadata for this object. + +Signature: + +```typescript +export declare function updateMetadata(ref: StorageReference, metadata: SettableMetadata): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) to update metadata for. | +| metadata | [SettableMetadata](./storage.settablemetadata.md#settablemetadata_interface) | The new metadata for the object. Only values that have been explicitly set will be changed. Explicitly setting a value to null will remove the metadata. | + +Returns: + +Promise<[FullMetadata](./storage.fullmetadata.md#fullmetadata_interface)> + +A `Promise` that resolves with the new metadata for this object. + +## uploadBytes() + +Uploads data to this object's location. The upload is not resumable. + +Signature: + +```typescript +export declare function uploadBytes(ref: StorageReference, data: Blob | Uint8Array | ArrayBuffer, metadata?: UploadMetadata): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) where data should be uploaded. | +| data | Blob \| Uint8Array \| ArrayBuffer | The data to upload. | +| metadata | [UploadMetadata](./storage.uploadmetadata.md#uploadmetadata_interface) | Metadata for the data to upload. | + +Returns: + +Promise<[UploadResult](./storage.uploadresult.md#uploadresult_interface)> + +A Promise containing an UploadResult + +## uploadBytesResumable() + +Uploads data to this object's location. The upload can be paused and resumed, and exposes progress updates. + +Signature: + +```typescript +export declare function uploadBytesResumable(ref: StorageReference, data: Blob | Uint8Array | ArrayBuffer, metadata?: UploadMetadata): UploadTask; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) where data should be uploaded. | +| data | Blob \| Uint8Array \| ArrayBuffer | The data to upload. | +| metadata | [UploadMetadata](./storage.uploadmetadata.md#uploadmetadata_interface) | Metadata for the data to upload. | + +Returns: + +[UploadTask](./storage.uploadtask.md#uploadtask_interface) + +An UploadTask + +## uploadString() + +Uploads a string to this object's location. The upload is not resumable. + +Signature: + +```typescript +export declare function uploadString(ref: StorageReference, value: string, format?: StringFormat, metadata?: UploadMetadata): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) where string should be uploaded. | +| value | string | The string to upload. | +| format | [StringFormat](./storage.md#stringformat) | The format of the string to upload. | +| metadata | [UploadMetadata](./storage.uploadmetadata.md#uploadmetadata_interface) | Metadata for the string to upload. | + +Returns: + +Promise<[UploadResult](./storage.uploadresult.md#uploadresult_interface)> + +A Promise containing an UploadResult + +## ref() + +Returns a [StorageReference](./storage.storagereference.md#storagereference_interface) for the given path in the default bucket. + +Signature: + +```typescript +export declare function ref(storageOrRef: FirebaseStorage | StorageReference, path?: string): StorageReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| storageOrRef | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) \| [StorageReference](./storage.storagereference.md#storagereference_interface) | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) or [StorageReference](./storage.storagereference.md#storagereference_interface). | +| path | string | | + +Returns: + +[StorageReference](./storage.storagereference.md#storagereference_interface) + +## StringFormat + +An enumeration of the possible string formats for upload. + +Signature: + +```typescript +StringFormat: { + readonly RAW: "raw"; + readonly BASE64: "base64"; + readonly BASE64URL: "base64url"; + readonly DATA_URL: "data_url"; +} +``` + +## StringFormat + +An enumeration of the possible string formats for upload. + +Signature: + +```typescript +export declare type StringFormat = typeof StringFormat[keyof typeof StringFormat]; +``` + +## TaskEvent + +An event that is triggered on a task. + +Signature: + +```typescript +export declare type TaskEvent = 'state_changed'; +``` + +## TaskState + +Represents the current state of a running upload. + +Signature: + +```typescript +export declare type TaskState = 'running' | 'paused' | 'success' | 'canceled' | 'error'; +``` + +## StorageErrorCode + +Error codes that can be attached to `StorageError` objects. + +Signature: + +```typescript +export declare enum StorageErrorCode +``` + +## Enumeration Members + +| Member | Value | Description | +| --- | --- | --- | +| APP\_DELETED | "app-deleted" | | +| BUCKET\_NOT\_FOUND | "bucket-not-found" | | +| CANCELED | "canceled" | | +| CANNOT\_SLICE\_BLOB | "cannot-slice-blob" | | +| INTERNAL\_ERROR | "internal-error" | | +| INVALID\_ARGUMENT | "invalid-argument" | | +| INVALID\_ARGUMENT\_COUNT | "invalid-argument-count" | | +| INVALID\_CHECKSUM | "invalid-checksum" | | +| INVALID\_DEFAULT\_BUCKET | "invalid-default-bucket" | | +| INVALID\_EVENT\_NAME | "invalid-event-name" | | +| INVALID\_FORMAT | "invalid-format" | | +| INVALID\_ROOT\_OPERATION | "invalid-root-operation" | | +| INVALID\_URL | "invalid-url" | | +| NO\_DEFAULT\_BUCKET | "no-default-bucket" | | +| NO\_DOWNLOAD\_URL | "no-download-url" | | +| OBJECT\_NOT\_FOUND | "object-not-found" | | +| PROJECT\_NOT\_FOUND | "project-not-found" | | +| QUOTA\_EXCEEDED | "quota-exceeded" | | +| RETRY\_LIMIT\_EXCEEDED | "retry-limit-exceeded" | | +| SERVER\_FILE\_WRONG\_SIZE | "server-file-wrong-size" | | +| UNAUTHENTICATED | "unauthenticated" | | +| UNAUTHORIZED | "unauthorized" | | +| UNAUTHORIZED\_APP | "unauthorized-app" | | +| UNKNOWN | "unknown" | | +| UNSUPPORTED\_ENVIRONMENT | "unsupported-environment" | | + diff --git a/docs-devsite/storage.settablemetadata.md b/docs-devsite/storage.settablemetadata.md new file mode 100644 index 00000000000..c721cc6c4f0 --- /dev/null +++ b/docs-devsite/storage.settablemetadata.md @@ -0,0 +1,92 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# SettableMetadata interface +Object metadata that can be set at any time. + +Signature: + +```typescript +export interface SettableMetadata +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [cacheControl](./storage.settablemetadata.md#settablemetadatacachecontrol) | string \| undefined | Served as the 'Cache-Control' header on object download. | +| [contentDisposition](./storage.settablemetadata.md#settablemetadatacontentdisposition) | string \| undefined | Served as the 'Content-Disposition' header on object download. | +| [contentEncoding](./storage.settablemetadata.md#settablemetadatacontentencoding) | string \| undefined | Served as the 'Content-Encoding' header on object download. | +| [contentLanguage](./storage.settablemetadata.md#settablemetadatacontentlanguage) | string \| undefined | Served as the 'Content-Language' header on object download. | +| [contentType](./storage.settablemetadata.md#settablemetadatacontenttype) | string \| undefined | Served as the 'Content-Type' header on object download. | +| [customMetadata](./storage.settablemetadata.md#settablemetadatacustommetadata) | { \[key: string\]: string; } \| undefined | Additional user-defined custom metadata. | + +## SettableMetadata.cacheControl + +Served as the 'Cache-Control' header on object download. + +Signature: + +```typescript +cacheControl?: string | undefined; +``` + +## SettableMetadata.contentDisposition + +Served as the 'Content-Disposition' header on object download. + +Signature: + +```typescript +contentDisposition?: string | undefined; +``` + +## SettableMetadata.contentEncoding + +Served as the 'Content-Encoding' header on object download. + +Signature: + +```typescript +contentEncoding?: string | undefined; +``` + +## SettableMetadata.contentLanguage + +Served as the 'Content-Language' header on object download. + +Signature: + +```typescript +contentLanguage?: string | undefined; +``` + +## SettableMetadata.contentType + +Served as the 'Content-Type' header on object download. + +Signature: + +```typescript +contentType?: string | undefined; +``` + +## SettableMetadata.customMetadata + +Additional user-defined custom metadata. + +Signature: + +```typescript +customMetadata?: { + [key: string]: string; + } | undefined; +``` diff --git a/docs-devsite/storage.storageerror.md b/docs-devsite/storage.storageerror.md new file mode 100644 index 00000000000..9e460e47db7 --- /dev/null +++ b/docs-devsite/storage.storageerror.md @@ -0,0 +1,113 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# StorageError class +An error returned by the Firebase Storage SDK. + +Signature: + +```typescript +export declare class StorageError extends FirebaseError +``` +Extends: [FirebaseError](./util.firebaseerror.md#firebaseerror_class) + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(code, message, status\_)](./storage.storageerror.md#storageerrorconstructor) | | Constructs a new instance of the StorageError class | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [customData](./storage.storageerror.md#storageerrorcustomdata) | | { serverResponse: string \| null; } | Stores custom error data unique to the StorageError. | +| [serverResponse](./storage.storageerror.md#storageerrorserverresponse) | | null \| string | Optional response message that was added by the server. | +| [status](./storage.storageerror.md#storageerrorstatus) | | number | | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [\_codeEquals(code)](./storage.storageerror.md#storageerror_codeequals) | | Compares a StorageErrorCode against this error's code, filtering out the prefix. | + +## StorageError.(constructor) + +Constructs a new instance of the `StorageError` class + +Signature: + +```typescript +constructor(code: StorageErrorCode, message: string, status_?: number); +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| code | [StorageErrorCode](./storage.md#storageerrorcode) | A StorageErrorCode string to be prefixed with 'storage/' and added to the end of the message. | +| message | string | Error message. | +| status\_ | number | Corresponding HTTP Status Code | + +## StorageError.customData + +Stores custom error data unique to the `StorageError`. + +Signature: + +```typescript +customData: { + serverResponse: string | null; + }; +``` + +## StorageError.serverResponse + +Optional response message that was added by the server. + +Signature: + +```typescript +get serverResponse(): null | string; + +set serverResponse(serverResponse: string | null); +``` + +## StorageError.status + +Signature: + +```typescript +get status(): number; + +set status(status: number); +``` + +## StorageError.\_codeEquals() + +Compares a `StorageErrorCode` against this error's code, filtering out the prefix. + +Signature: + +```typescript +_codeEquals(code: StorageErrorCode): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| code | [StorageErrorCode](./storage.md#storageerrorcode) | | + +Returns: + +boolean + diff --git a/docs-devsite/storage.storageobserver.md b/docs-devsite/storage.storageobserver.md new file mode 100644 index 00000000000..583ddca7c3d --- /dev/null +++ b/docs-devsite/storage.storageobserver.md @@ -0,0 +1,51 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# StorageObserver interface +A stream observer for Firebase Storage. + +Signature: + +```typescript +export interface StorageObserver +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [complete](./storage.storageobserver.md#storageobservercomplete) | [CompleteFn](./util.md#completefn) \| null | | +| [error](./storage.storageobserver.md#storageobservererror) | (error: [StorageError](./storage.storageerror.md#storageerror_class)) => void \| null | | +| [next](./storage.storageobserver.md#storageobservernext) | [NextFn](./util.md#nextfn)<T> \| null | | + +## StorageObserver.complete + +Signature: + +```typescript +complete?: CompleteFn | null; +``` + +## StorageObserver.error + +Signature: + +```typescript +error?: (error: StorageError) => void | null; +``` + +## StorageObserver.next + +Signature: + +```typescript +next?: NextFn | null; +``` diff --git a/docs-devsite/storage.storagereference.md b/docs-devsite/storage.storagereference.md new file mode 100644 index 00000000000..4b584a428d5 --- /dev/null +++ b/docs-devsite/storage.storagereference.md @@ -0,0 +1,112 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# StorageReference interface +Represents a reference to a Google Cloud Storage object. Developers can upload, download, and delete objects, as well as get/set object metadata. + +Signature: + +```typescript +export interface StorageReference +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [bucket](./storage.storagereference.md#storagereferencebucket) | string | The name of the bucket containing this reference's object. | +| [fullPath](./storage.storagereference.md#storagereferencefullpath) | string | The full path of this object. | +| [name](./storage.storagereference.md#storagereferencename) | string | The short name of this object, which is the last component of the full path. For example, if fullPath is 'full/path/image.png', name is 'image.png'. | +| [parent](./storage.storagereference.md#storagereferenceparent) | [StorageReference](./storage.storagereference.md#storagereference_interface) \| null | A reference pointing to the parent location of this reference, or null if this reference is the root. | +| [root](./storage.storagereference.md#storagereferenceroot) | [StorageReference](./storage.storagereference.md#storagereference_interface) | A reference to the root of this object's bucket. | +| [storage](./storage.storagereference.md#storagereferencestorage) | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) | The [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance associated with this reference. | + +## Methods + +| Method | Description | +| --- | --- | +| [toString()](./storage.storagereference.md#storagereferencetostring) | Returns a gs:// URL for this object in the form gs://<bucket>/<path>/<to>/<object> | + +## StorageReference.bucket + +The name of the bucket containing this reference's object. + +Signature: + +```typescript +bucket: string; +``` + +## StorageReference.fullPath + +The full path of this object. + +Signature: + +```typescript +fullPath: string; +``` + +## StorageReference.name + +The short name of this object, which is the last component of the full path. For example, if fullPath is 'full/path/image.png', name is 'image.png'. + +Signature: + +```typescript +name: string; +``` + +## StorageReference.parent + +A reference pointing to the parent location of this reference, or null if this reference is the root. + +Signature: + +```typescript +parent: StorageReference | null; +``` + +## StorageReference.root + +A reference to the root of this object's bucket. + +Signature: + +```typescript +root: StorageReference; +``` + +## StorageReference.storage + +The [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance associated with this reference. + +Signature: + +```typescript +storage: FirebaseStorage; +``` + +## StorageReference.toString() + +Returns a gs:// URL for this object in the form `gs://///` + +Signature: + +```typescript +toString(): string; +``` +Returns: + +string + +The gs:// URL. + diff --git a/docs-devsite/storage.uploadmetadata.md b/docs-devsite/storage.uploadmetadata.md new file mode 100644 index 00000000000..2b207401736 --- /dev/null +++ b/docs-devsite/storage.uploadmetadata.md @@ -0,0 +1,36 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# UploadMetadata interface +Object metadata that can be set at upload. + +Signature: + +```typescript +export interface UploadMetadata extends SettableMetadata +``` +Extends: [SettableMetadata](./storage.settablemetadata.md#settablemetadata_interface) + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [md5Hash](./storage.uploadmetadata.md#uploadmetadatamd5hash) | string \| undefined | A Base64-encoded MD5 hash of the object being uploaded. | + +## UploadMetadata.md5Hash + +A Base64-encoded MD5 hash of the object being uploaded. + +Signature: + +```typescript +md5Hash?: string | undefined; +``` diff --git a/docs-devsite/storage.uploadresult.md b/docs-devsite/storage.uploadresult.md new file mode 100644 index 00000000000..05e3542ee62 --- /dev/null +++ b/docs-devsite/storage.uploadresult.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# UploadResult interface +Result returned from a non-resumable upload. + +Signature: + +```typescript +export interface UploadResult +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [metadata](./storage.uploadresult.md#uploadresultmetadata) | [FullMetadata](./storage.fullmetadata.md#fullmetadata_interface) | Contains the metadata sent back from the server. | +| [ref](./storage.uploadresult.md#uploadresultref) | [StorageReference](./storage.storagereference.md#storagereference_interface) | The reference that spawned this upload. | + +## UploadResult.metadata + +Contains the metadata sent back from the server. + +Signature: + +```typescript +readonly metadata: FullMetadata; +``` + +## UploadResult.ref + +The reference that spawned this upload. + +Signature: + +```typescript +readonly ref: StorageReference; +``` diff --git a/docs-devsite/storage.uploadtask.md b/docs-devsite/storage.uploadtask.md new file mode 100644 index 00000000000..af4bff4088e --- /dev/null +++ b/docs-devsite/storage.uploadtask.md @@ -0,0 +1,255 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# UploadTask interface +Represents the process of uploading an object. Allows you to monitor and manage the upload. + +Signature: + +```typescript +export interface UploadTask +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [snapshot](./storage.uploadtask.md#uploadtasksnapshot) | [UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface) | A snapshot of the current task state. | + +## Methods + +| Method | Description | +| --- | --- | +| [cancel()](./storage.uploadtask.md#uploadtaskcancel) | Cancels a running task. Has no effect on a complete or failed task. | +| [catch(onRejected)](./storage.uploadtask.md#uploadtaskcatch) | Equivalent to calling then(null, onRejected). | +| [on(event, nextOrObserver, error, complete)](./storage.uploadtask.md#uploadtaskon) | Listens for events on this task.Events have three callback functions (referred to as next, error, and complete).If only the event is passed, a function that can be used to register the callbacks is returned. Otherwise, the callbacks are passed after the event.Callbacks can be passed either as three separate arguments or as the next, error, and complete properties of an object. Any of the three callbacks is optional, as long as at least one is specified. In addition, when you add your callbacks, you get a function back. You can call this function to unregister the associated callbacks. | +| [pause()](./storage.uploadtask.md#uploadtaskpause) | Pauses a currently running task. Has no effect on a paused or failed task. | +| [resume()](./storage.uploadtask.md#uploadtaskresume) | Resumes a paused task. Has no effect on a currently running or failed task. | +| [then(onFulfilled, onRejected)](./storage.uploadtask.md#uploadtaskthen) | This object behaves like a Promise, and resolves with its snapshot data when the upload completes. | + +## UploadTask.snapshot + +A snapshot of the current task state. + +Signature: + +```typescript +snapshot: UploadTaskSnapshot; +``` + +## UploadTask.cancel() + +Cancels a running task. Has no effect on a complete or failed task. + +Signature: + +```typescript +cancel(): boolean; +``` +Returns: + +boolean + +True if the cancel had an effect. + +## UploadTask.catch() + +Equivalent to calling `then(null, onRejected)`. + +Signature: + +```typescript +catch(onRejected: (error: StorageError) => unknown): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| onRejected | (error: [StorageError](./storage.storageerror.md#storageerror_class)) => unknown | | + +Returns: + +Promise<unknown> + +## UploadTask.on() + +Listens for events on this task. + +Events have three callback functions (referred to as `next`, `error`, and `complete`). + +If only the event is passed, a function that can be used to register the callbacks is returned. Otherwise, the callbacks are passed after the event. + +Callbacks can be passed either as three separate arguments or as the `next`, `error`, and `complete` properties of an object. Any of the three callbacks is optional, as long as at least one is specified. In addition, when you add your callbacks, you get a function back. You can call this function to unregister the associated callbacks. + +Signature: + +```typescript +on(event: TaskEvent, nextOrObserver?: StorageObserver | null | ((snapshot: UploadTaskSnapshot) => unknown), error?: ((a: StorageError) => unknown) | null, complete?: Unsubscribe | null): Unsubscribe | Subscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| event | [TaskEvent](./storage.md#taskevent) | The type of event to listen for. | +| nextOrObserver | [StorageObserver](./storage.storageobserver.md#storageobserver_interface)<[UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface)> \| null \| ((snapshot: [UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface)) => unknown) | The next function, which gets called for each item in the event stream, or an observer object with some or all of these three properties (next, error, complete). | +| error | ((a: [StorageError](./storage.storageerror.md#storageerror_class)) => unknown) \| null | A function that gets called with a StorageError if the event stream ends due to an error. | +| complete | [Unsubscribe](./util.md#unsubscribe) \| null | | + +Returns: + +[Unsubscribe](./util.md#unsubscribe) \| [Subscribe](./util.subscribe.md#subscribe_interface)<[UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface)> + +If only the event argument is passed, returns a function you can use to add callbacks (see the examples above). If more than just the event argument is passed, returns a function you can call to unregister the callbacks. + +### Example 1 + +\*\*Pass callbacks separately or in an object.\*\* + +```javascript +var next = function(snapshot) {}; +var error = function(error) {}; +var complete = function() {}; + +// The first example. +uploadTask.on( + firebase.storage.TaskEvent.STATE_CHANGED, + next, + error, + complete); + +// This is equivalent to the first example. +uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED, { + 'next': next, + 'error': error, + 'complete': complete +}); + +// This is equivalent to the first example. +var subscribe = uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED); +subscribe(next, error, complete); + +// This is equivalent to the first example. +var subscribe = uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED); +subscribe({ + 'next': next, + 'error': error, + 'complete': complete +}); + +``` + +### Example 2 + +\*\*Any callback is optional.\*\* + +```javascript +// Just listening for completion, this is legal. +uploadTask.on( + firebase.storage.TaskEvent.STATE_CHANGED, + null, + null, + function() { + console.log('upload complete!'); + }); + +// Just listening for progress/state changes, this is legal. +uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED, function(snapshot) { + var percent = snapshot.bytesTransferred / snapshot.totalBytes * 100; + console.log(percent + "% done"); +}); + +// This is also legal. +uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED, { + 'complete': function() { + console.log('upload complete!'); + } +}); + +``` + +### Example 3 + +\*\*Use the returned function to remove callbacks.\*\* + +```javascript +var unsubscribe = uploadTask.on( + firebase.storage.TaskEvent.STATE_CHANGED, + function(snapshot) { + var percent = snapshot.bytesTransferred / snapshot.totalBytes * 100; + console.log(percent + "% done"); + // Stop after receiving one update. + unsubscribe(); + }); + +// This code is equivalent to the above. +var handle = uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED); +unsubscribe = handle(function(snapshot) { + var percent = snapshot.bytesTransferred / snapshot.totalBytes * 100; + console.log(percent + "% done"); + // Stop after receiving one update. + unsubscribe(); +}); + +``` + +## UploadTask.pause() + +Pauses a currently running task. Has no effect on a paused or failed task. + +Signature: + +```typescript +pause(): boolean; +``` +Returns: + +boolean + +True if the operation took effect, false if ignored. + +## UploadTask.resume() + +Resumes a paused task. Has no effect on a currently running or failed task. + +Signature: + +```typescript +resume(): boolean; +``` +Returns: + +boolean + +True if the operation took effect, false if ignored. + +## UploadTask.then() + +This object behaves like a Promise, and resolves with its snapshot data when the upload completes. + +Signature: + +```typescript +then(onFulfilled?: ((snapshot: UploadTaskSnapshot) => unknown) | null, onRejected?: ((error: StorageError) => unknown) | null): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| onFulfilled | ((snapshot: [UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface)) => unknown) \| null | The fulfillment callback. Promise chaining works as normal. | +| onRejected | ((error: [StorageError](./storage.storageerror.md#storageerror_class)) => unknown) \| null | The rejection callback. | + +Returns: + +Promise<unknown> + diff --git a/docs-devsite/storage.uploadtasksnapshot.md b/docs-devsite/storage.uploadtasksnapshot.md new file mode 100644 index 00000000000..351ff7a2154 --- /dev/null +++ b/docs-devsite/storage.uploadtasksnapshot.md @@ -0,0 +1,90 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# UploadTaskSnapshot interface +Holds data about the current state of the upload task. + +Signature: + +```typescript +export interface UploadTaskSnapshot +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [bytesTransferred](./storage.uploadtasksnapshot.md#uploadtasksnapshotbytestransferred) | number | The number of bytes that have been successfully uploaded so far. | +| [metadata](./storage.uploadtasksnapshot.md#uploadtasksnapshotmetadata) | [FullMetadata](./storage.fullmetadata.md#fullmetadata_interface) | Before the upload completes, contains the metadata sent to the server. After the upload completes, contains the metadata sent back from the server. | +| [ref](./storage.uploadtasksnapshot.md#uploadtasksnapshotref) | [StorageReference](./storage.storagereference.md#storagereference_interface) | The reference that spawned this snapshot's upload task. | +| [state](./storage.uploadtasksnapshot.md#uploadtasksnapshotstate) | [TaskState](./storage.md#taskstate) | The current state of the task. | +| [task](./storage.uploadtasksnapshot.md#uploadtasksnapshottask) | [UploadTask](./storage.uploadtask.md#uploadtask_interface) | The task of which this is a snapshot. | +| [totalBytes](./storage.uploadtasksnapshot.md#uploadtasksnapshottotalbytes) | number | The total number of bytes to be uploaded. | + +## UploadTaskSnapshot.bytesTransferred + +The number of bytes that have been successfully uploaded so far. + +Signature: + +```typescript +bytesTransferred: number; +``` + +## UploadTaskSnapshot.metadata + +Before the upload completes, contains the metadata sent to the server. After the upload completes, contains the metadata sent back from the server. + +Signature: + +```typescript +metadata: FullMetadata; +``` + +## UploadTaskSnapshot.ref + +The reference that spawned this snapshot's upload task. + +Signature: + +```typescript +ref: StorageReference; +``` + +## UploadTaskSnapshot.state + +The current state of the task. + +Signature: + +```typescript +state: TaskState; +``` + +## UploadTaskSnapshot.task + +The task of which this is a snapshot. + +Signature: + +```typescript +task: UploadTask; +``` + +## UploadTaskSnapshot.totalBytes + +The total number of bytes to be uploaded. + +Signature: + +```typescript +totalBytes: number; +``` diff --git a/packages/auth/api-extractor.json b/packages/auth/api-extractor.json index bd0dda5cca2..06ff1e940cf 100644 --- a/packages/auth/api-extractor.json +++ b/packages/auth/api-extractor.json @@ -1,6 +1,6 @@ { "extends": "../../config/api-extractor.json", - "mainEntryPointFilePath": "/dist/esm5/index.d.ts", + "mainEntryPointFilePath": "/dist/esm5/index.doc.d.ts", "dtsRollup": { "enabled": true, "untrimmedFilePath": "/dist/.d.ts", diff --git a/scripts/docgen/docgen.ts b/scripts/docgen/docgen.ts index c2f39b24469..77284fc539b 100644 --- a/scripts/docgen/docgen.ts +++ b/scripts/docgen/docgen.ts @@ -145,12 +145,21 @@ async function generateDocs( authApiConfigModified ); - if (!skipBuild) { - await spawn('yarn', ['build'], { + if (skipBuild) { + await spawn('yarn', ['api-report'], { stdio: 'inherit' }); - - await spawn('yarn', ['api-report'], { + } else { + // api-report is run as part of every build + await spawn('yarn', [ + 'lerna', + 'run', + '--scope', + '@firebase/*', + '--ignore', + '@firebase/*-compat', + 'build' + ], { stdio: 'inherit' }); } From 624601df7a66dc73879b0e15f3f085623a4b1f3f Mon Sep 17 00:00:00 2001 From: Christina Holland Date: Mon, 13 Feb 2023 12:34:12 -0800 Subject: [PATCH 07/12] rm docs for now --- docs-devsite/analytics.analytics.md | 35 - .../analytics.analyticscalloptions.md | 35 - docs-devsite/analytics.analyticssettings.md | 35 - docs-devsite/analytics.consentsettings.md | 79 - docs-devsite/analytics.controlparams.md | 60 - docs-devsite/analytics.customparams.md | 19 - docs-devsite/analytics.eventparams.md | 316 --- docs-devsite/analytics.gtagconfigparams.md | 134 -- docs-devsite/analytics.item.md | 278 --- docs-devsite/analytics.md | 991 -------- docs-devsite/analytics.promotion.md | 65 - docs-devsite/analytics.settingsoptions.md | 46 - docs-devsite/app-check.appcheck.md | 35 - docs-devsite/app-check.appcheckoptions.md | 46 - docs-devsite/app-check.appchecktoken.md | 44 - docs-devsite/app-check.appchecktokenresult.md | 35 - docs-devsite/app-check.customprovider.md | 43 - .../app-check.customprovideroptions.md | 35 - docs-devsite/app-check.md | 170 -- .../app-check.recaptchaenterpriseprovider.md | 43 - docs-devsite/app-check.recaptchav3provider.md | 43 - docs-devsite/app.firebaseapp.md | 91 - docs-devsite/app.firebaseappsettings.md | 46 - docs-devsite/app.firebaseoptions.md | 112 - docs-devsite/app.md | 306 --- docs-devsite/auth.actioncodeinfo.md | 58 - docs-devsite/auth.actioncodesettings.md | 95 - docs-devsite/auth.actioncodeurl.md | 121 - docs-devsite/auth.additionaluserinfo.md | 68 - docs-devsite/auth.applicationverifier.md | 59 - docs-devsite/auth.auth.md | 299 --- docs-devsite/auth.authcredential.md | 76 - docs-devsite/auth.autherror.md | 41 - docs-devsite/auth.autherrormap.md | 27 - docs-devsite/auth.authprovider.md | 35 - docs-devsite/auth.authsettings.md | 41 - docs-devsite/auth.config.md | 90 - docs-devsite/auth.confirmationresult.md | 74 - docs-devsite/auth.dependencies.md | 63 - docs-devsite/auth.emailauthcredential.md | 69 - docs-devsite/auth.emailauthprovider.md | 159 -- docs-devsite/auth.emulatorconfig.md | 70 - docs-devsite/auth.facebookauthprovider.md | 182 -- docs-devsite/auth.githubauthprovider.md | 174 -- docs-devsite/auth.googleauthprovider.md | 185 -- docs-devsite/auth.idtokenresult.md | 109 - docs-devsite/auth.md | 1992 --------------- docs-devsite/auth.multifactorassertion.md | 37 - docs-devsite/auth.multifactorerror.md | 67 - docs-devsite/auth.multifactorinfo.md | 68 - docs-devsite/auth.multifactorresolver.md | 128 - docs-devsite/auth.multifactorsession.md | 19 - docs-devsite/auth.multifactoruser.md | 161 -- docs-devsite/auth.oauthcredential.md | 105 - docs-devsite/auth.oauthcredentialoptions.md | 61 - docs-devsite/auth.oauthprovider.md | 168 -- docs-devsite/auth.parsedtoken.md | 83 - docs-devsite/auth.persistence.md | 35 - docs-devsite/auth.phoneauthcredential.md | 63 - docs-devsite/auth.phoneauthprovider.md | 256 -- .../auth.phonemultifactorassertion.md | 21 - .../auth.phonemultifactorenrollinfooptions.md | 46 - .../auth.phonemultifactorgenerator.md | 64 - docs-devsite/auth.phonemultifactorinfo.md | 36 - .../auth.phonemultifactorsignininfooptions.md | 61 - .../auth.phonesinglefactorinfooptions.md | 35 - docs-devsite/auth.popupredirectresolver.md | 19 - docs-devsite/auth.reactnativeasyncstorage.md | 89 - docs-devsite/auth.recaptchaparameters.md | 23 - docs-devsite/auth.recaptchaverifier.md | 116 - docs-devsite/auth.samlauthprovider.md | 119 - docs-devsite/auth.twitterauthprovider.md | 173 -- docs-devsite/auth.user.md | 204 -- docs-devsite/auth.usercredential.md | 59 - docs-devsite/auth.userinfo.md | 92 - docs-devsite/auth.usermetadata.md | 46 - docs-devsite/database.database.md | 46 - docs-devsite/database.databasereference.md | 68 - docs-devsite/database.datasnapshot.md | 237 -- docs-devsite/database.listenoptions.md | 35 - docs-devsite/database.md | 1405 ----------- docs-devsite/database.ondisconnect.md | 143 -- docs-devsite/database.query.md | 108 - docs-devsite/database.queryconstraint.md | 35 - docs-devsite/database.thenablereference.md | 21 - docs-devsite/database.transactionoptions.md | 35 - docs-devsite/database.transactionresult.md | 66 - docs-devsite/firestore.md | 19 - docs-devsite/firestore_.aggregatefield.md | 35 - .../firestore_.aggregatequerysnapshot.md | 70 - docs-devsite/firestore_.aggregatespec.md | 19 - docs-devsite/firestore_.bytes.md | 138 -- .../firestore_.collectionreference.md | 121 - docs-devsite/firestore_.documentchange.md | 68 - docs-devsite/firestore_.documentdata.md | 19 - docs-devsite/firestore_.documentreference.md | 142 -- docs-devsite/firestore_.documentsnapshot.md | 146 -- docs-devsite/firestore_.fieldpath.md | 72 - docs-devsite/firestore_.fieldvalue.md | 46 - docs-devsite/firestore_.firestore.md | 68 - .../firestore_.firestoredataconverter.md | 134 -- docs-devsite/firestore_.firestoreerror.md | 58 - docs-devsite/firestore_.firestoresettings.md | 96 - docs-devsite/firestore_.geopoint.md | 117 - docs-devsite/firestore_.index.md | 55 - docs-devsite/firestore_.indexconfiguration.md | 43 - docs-devsite/firestore_.indexfield.md | 73 - docs-devsite/firestore_.loadbundletask.md | 94 - .../firestore_.loadbundletaskprogress.md | 79 - docs-devsite/firestore_.md | 2134 ----------------- .../firestore_.persistencesettings.md | 35 - docs-devsite/firestore_.query.md | 125 - docs-devsite/firestore_.queryconstraint.md | 35 - .../firestore_.querydocumentsnapshot.md | 54 - .../firestore_.queryendatconstraint.md | 36 - .../firestore_.queryfieldfilterconstraint.md | 36 - .../firestore_.querylimitconstraint.md | 36 - .../firestore_.queryorderbyconstraint.md | 38 - docs-devsite/firestore_.querysnapshot.md | 128 - .../firestore_.querystartatconstraint.md | 36 - .../firestore_.snapshotlistenoptions.md | 35 - docs-devsite/firestore_.snapshotmetadata.md | 75 - docs-devsite/firestore_.snapshotoptions.md | 41 - docs-devsite/firestore_.timestamp.md | 243 -- docs-devsite/firestore_.transaction.md | 190 -- docs-devsite/firestore_.transactionoptions.md | 35 - docs-devsite/firestore_.unsubscribe.md | 19 - docs-devsite/firestore_.writebatch.md | 181 -- docs-devsite/firestore_lite.aggregatefield.md | 35 - .../firestore_lite.aggregatequerysnapshot.md | 70 - docs-devsite/firestore_lite.aggregatespec.md | 19 - docs-devsite/firestore_lite.bytes.md | 138 -- .../firestore_lite.collectionreference.md | 121 - docs-devsite/firestore_lite.documentdata.md | 19 - .../firestore_lite.documentreference.md | 142 -- .../firestore_lite.documentsnapshot.md | 125 - docs-devsite/firestore_lite.fieldpath.md | 72 - docs-devsite/firestore_lite.fieldvalue.md | 46 - docs-devsite/firestore_lite.firestore.md | 68 - .../firestore_lite.firestoredataconverter.md | 130 - docs-devsite/firestore_lite.firestoreerror.md | 58 - docs-devsite/firestore_lite.geopoint.md | 117 - docs-devsite/firestore_lite.md | 1443 ----------- docs-devsite/firestore_lite.query.md | 125 - .../firestore_lite.queryconstraint.md | 35 - .../firestore_lite.querydocumentsnapshot.md | 45 - .../firestore_lite.queryendatconstraint.md | 36 - ...restore_lite.queryfieldfilterconstraint.md | 36 - .../firestore_lite.querylimitconstraint.md | 36 - .../firestore_lite.queryorderbyconstraint.md | 38 - docs-devsite/firestore_lite.querysnapshot.md | 96 - .../firestore_lite.querystartatconstraint.md | 36 - docs-devsite/firestore_lite.settings.md | 57 - docs-devsite/firestore_lite.timestamp.md | 243 -- docs-devsite/firestore_lite.transaction.md | 190 -- .../firestore_lite.transactionoptions.md | 35 - docs-devsite/firestore_lite.writebatch.md | 181 -- docs-devsite/functions.functions.md | 57 - docs-devsite/functions.functionserror.md | 47 - .../functions.httpscallableoptions.md | 35 - docs-devsite/functions.httpscallableresult.md | 35 - docs-devsite/functions.md | 162 -- docs-devsite/index.md | 30 - docs-devsite/installations.installations.md | 35 - docs-devsite/installations.md | 162 -- docs-devsite/messaging.md | 19 - docs-devsite/messaging_.fcmoptions.md | 46 - docs-devsite/messaging_.gettokenoptions.md | 46 - docs-devsite/messaging_.md | 143 -- docs-devsite/messaging_.messagepayload.md | 92 - docs-devsite/messaging_.messaging.md | 35 - .../messaging_.notificationpayload.md | 68 - docs-devsite/messaging_sw.fcmoptions.md | 46 - docs-devsite/messaging_sw.gettokenoptions.md | 46 - docs-devsite/messaging_sw.md | 116 - docs-devsite/messaging_sw.messagepayload.md | 92 - docs-devsite/messaging_sw.messaging.md | 35 - .../messaging_sw.notificationpayload.md | 68 - .../performance.firebaseperformance.md | 57 - docs-devsite/performance.md | 94 - .../performance.performancesettings.md | 46 - docs-devsite/performance.performancetrace.md | 228 -- docs-devsite/remote-config.md | 345 --- docs-devsite/remote-config.remoteconfig.md | 81 - .../remote-config.remoteconfigsettings.md | 46 - docs-devsite/remote-config.value.md | 83 - docs-devsite/storage.firebasestorage.md | 58 - docs-devsite/storage.fullmetadata.md | 135 -- docs-devsite/storage.listoptions.md | 46 - docs-devsite/storage.listresult.md | 59 - docs-devsite/storage.md | 550 ----- docs-devsite/storage.settablemetadata.md | 92 - docs-devsite/storage.storageerror.md | 113 - docs-devsite/storage.storageobserver.md | 51 - docs-devsite/storage.storagereference.md | 112 - docs-devsite/storage.uploadmetadata.md | 36 - docs-devsite/storage.uploadresult.md | 46 - docs-devsite/storage.uploadtask.md | 255 -- docs-devsite/storage.uploadtasksnapshot.md | 90 - 199 files changed, 24936 deletions(-) delete mode 100644 docs-devsite/analytics.analytics.md delete mode 100644 docs-devsite/analytics.analyticscalloptions.md delete mode 100644 docs-devsite/analytics.analyticssettings.md delete mode 100644 docs-devsite/analytics.consentsettings.md delete mode 100644 docs-devsite/analytics.controlparams.md delete mode 100644 docs-devsite/analytics.customparams.md delete mode 100644 docs-devsite/analytics.eventparams.md delete mode 100644 docs-devsite/analytics.gtagconfigparams.md delete mode 100644 docs-devsite/analytics.item.md delete mode 100644 docs-devsite/analytics.md delete mode 100644 docs-devsite/analytics.promotion.md delete mode 100644 docs-devsite/analytics.settingsoptions.md delete mode 100644 docs-devsite/app-check.appcheck.md delete mode 100644 docs-devsite/app-check.appcheckoptions.md delete mode 100644 docs-devsite/app-check.appchecktoken.md delete mode 100644 docs-devsite/app-check.appchecktokenresult.md delete mode 100644 docs-devsite/app-check.customprovider.md delete mode 100644 docs-devsite/app-check.customprovideroptions.md delete mode 100644 docs-devsite/app-check.md delete mode 100644 docs-devsite/app-check.recaptchaenterpriseprovider.md delete mode 100644 docs-devsite/app-check.recaptchav3provider.md delete mode 100644 docs-devsite/app.firebaseapp.md delete mode 100644 docs-devsite/app.firebaseappsettings.md delete mode 100644 docs-devsite/app.firebaseoptions.md delete mode 100644 docs-devsite/app.md delete mode 100644 docs-devsite/auth.actioncodeinfo.md delete mode 100644 docs-devsite/auth.actioncodesettings.md delete mode 100644 docs-devsite/auth.actioncodeurl.md delete mode 100644 docs-devsite/auth.additionaluserinfo.md delete mode 100644 docs-devsite/auth.applicationverifier.md delete mode 100644 docs-devsite/auth.auth.md delete mode 100644 docs-devsite/auth.authcredential.md delete mode 100644 docs-devsite/auth.autherror.md delete mode 100644 docs-devsite/auth.autherrormap.md delete mode 100644 docs-devsite/auth.authprovider.md delete mode 100644 docs-devsite/auth.authsettings.md delete mode 100644 docs-devsite/auth.config.md delete mode 100644 docs-devsite/auth.confirmationresult.md delete mode 100644 docs-devsite/auth.dependencies.md delete mode 100644 docs-devsite/auth.emailauthcredential.md delete mode 100644 docs-devsite/auth.emailauthprovider.md delete mode 100644 docs-devsite/auth.emulatorconfig.md delete mode 100644 docs-devsite/auth.facebookauthprovider.md delete mode 100644 docs-devsite/auth.githubauthprovider.md delete mode 100644 docs-devsite/auth.googleauthprovider.md delete mode 100644 docs-devsite/auth.idtokenresult.md delete mode 100644 docs-devsite/auth.md delete mode 100644 docs-devsite/auth.multifactorassertion.md delete mode 100644 docs-devsite/auth.multifactorerror.md delete mode 100644 docs-devsite/auth.multifactorinfo.md delete mode 100644 docs-devsite/auth.multifactorresolver.md delete mode 100644 docs-devsite/auth.multifactorsession.md delete mode 100644 docs-devsite/auth.multifactoruser.md delete mode 100644 docs-devsite/auth.oauthcredential.md delete mode 100644 docs-devsite/auth.oauthcredentialoptions.md delete mode 100644 docs-devsite/auth.oauthprovider.md delete mode 100644 docs-devsite/auth.parsedtoken.md delete mode 100644 docs-devsite/auth.persistence.md delete mode 100644 docs-devsite/auth.phoneauthcredential.md delete mode 100644 docs-devsite/auth.phoneauthprovider.md delete mode 100644 docs-devsite/auth.phonemultifactorassertion.md delete mode 100644 docs-devsite/auth.phonemultifactorenrollinfooptions.md delete mode 100644 docs-devsite/auth.phonemultifactorgenerator.md delete mode 100644 docs-devsite/auth.phonemultifactorinfo.md delete mode 100644 docs-devsite/auth.phonemultifactorsignininfooptions.md delete mode 100644 docs-devsite/auth.phonesinglefactorinfooptions.md delete mode 100644 docs-devsite/auth.popupredirectresolver.md delete mode 100644 docs-devsite/auth.reactnativeasyncstorage.md delete mode 100644 docs-devsite/auth.recaptchaparameters.md delete mode 100644 docs-devsite/auth.recaptchaverifier.md delete mode 100644 docs-devsite/auth.samlauthprovider.md delete mode 100644 docs-devsite/auth.twitterauthprovider.md delete mode 100644 docs-devsite/auth.user.md delete mode 100644 docs-devsite/auth.usercredential.md delete mode 100644 docs-devsite/auth.userinfo.md delete mode 100644 docs-devsite/auth.usermetadata.md delete mode 100644 docs-devsite/database.database.md delete mode 100644 docs-devsite/database.databasereference.md delete mode 100644 docs-devsite/database.datasnapshot.md delete mode 100644 docs-devsite/database.listenoptions.md delete mode 100644 docs-devsite/database.md delete mode 100644 docs-devsite/database.ondisconnect.md delete mode 100644 docs-devsite/database.query.md delete mode 100644 docs-devsite/database.queryconstraint.md delete mode 100644 docs-devsite/database.thenablereference.md delete mode 100644 docs-devsite/database.transactionoptions.md delete mode 100644 docs-devsite/database.transactionresult.md delete mode 100644 docs-devsite/firestore.md delete mode 100644 docs-devsite/firestore_.aggregatefield.md delete mode 100644 docs-devsite/firestore_.aggregatequerysnapshot.md delete mode 100644 docs-devsite/firestore_.aggregatespec.md delete mode 100644 docs-devsite/firestore_.bytes.md delete mode 100644 docs-devsite/firestore_.collectionreference.md delete mode 100644 docs-devsite/firestore_.documentchange.md delete mode 100644 docs-devsite/firestore_.documentdata.md delete mode 100644 docs-devsite/firestore_.documentreference.md delete mode 100644 docs-devsite/firestore_.documentsnapshot.md delete mode 100644 docs-devsite/firestore_.fieldpath.md delete mode 100644 docs-devsite/firestore_.fieldvalue.md delete mode 100644 docs-devsite/firestore_.firestore.md delete mode 100644 docs-devsite/firestore_.firestoredataconverter.md delete mode 100644 docs-devsite/firestore_.firestoreerror.md delete mode 100644 docs-devsite/firestore_.firestoresettings.md delete mode 100644 docs-devsite/firestore_.geopoint.md delete mode 100644 docs-devsite/firestore_.index.md delete mode 100644 docs-devsite/firestore_.indexconfiguration.md delete mode 100644 docs-devsite/firestore_.indexfield.md delete mode 100644 docs-devsite/firestore_.loadbundletask.md delete mode 100644 docs-devsite/firestore_.loadbundletaskprogress.md delete mode 100644 docs-devsite/firestore_.md delete mode 100644 docs-devsite/firestore_.persistencesettings.md delete mode 100644 docs-devsite/firestore_.query.md delete mode 100644 docs-devsite/firestore_.queryconstraint.md delete mode 100644 docs-devsite/firestore_.querydocumentsnapshot.md delete mode 100644 docs-devsite/firestore_.queryendatconstraint.md delete mode 100644 docs-devsite/firestore_.queryfieldfilterconstraint.md delete mode 100644 docs-devsite/firestore_.querylimitconstraint.md delete mode 100644 docs-devsite/firestore_.queryorderbyconstraint.md delete mode 100644 docs-devsite/firestore_.querysnapshot.md delete mode 100644 docs-devsite/firestore_.querystartatconstraint.md delete mode 100644 docs-devsite/firestore_.snapshotlistenoptions.md delete mode 100644 docs-devsite/firestore_.snapshotmetadata.md delete mode 100644 docs-devsite/firestore_.snapshotoptions.md delete mode 100644 docs-devsite/firestore_.timestamp.md delete mode 100644 docs-devsite/firestore_.transaction.md delete mode 100644 docs-devsite/firestore_.transactionoptions.md delete mode 100644 docs-devsite/firestore_.unsubscribe.md delete mode 100644 docs-devsite/firestore_.writebatch.md delete mode 100644 docs-devsite/firestore_lite.aggregatefield.md delete mode 100644 docs-devsite/firestore_lite.aggregatequerysnapshot.md delete mode 100644 docs-devsite/firestore_lite.aggregatespec.md delete mode 100644 docs-devsite/firestore_lite.bytes.md delete mode 100644 docs-devsite/firestore_lite.collectionreference.md delete mode 100644 docs-devsite/firestore_lite.documentdata.md delete mode 100644 docs-devsite/firestore_lite.documentreference.md delete mode 100644 docs-devsite/firestore_lite.documentsnapshot.md delete mode 100644 docs-devsite/firestore_lite.fieldpath.md delete mode 100644 docs-devsite/firestore_lite.fieldvalue.md delete mode 100644 docs-devsite/firestore_lite.firestore.md delete mode 100644 docs-devsite/firestore_lite.firestoredataconverter.md delete mode 100644 docs-devsite/firestore_lite.firestoreerror.md delete mode 100644 docs-devsite/firestore_lite.geopoint.md delete mode 100644 docs-devsite/firestore_lite.md delete mode 100644 docs-devsite/firestore_lite.query.md delete mode 100644 docs-devsite/firestore_lite.queryconstraint.md delete mode 100644 docs-devsite/firestore_lite.querydocumentsnapshot.md delete mode 100644 docs-devsite/firestore_lite.queryendatconstraint.md delete mode 100644 docs-devsite/firestore_lite.queryfieldfilterconstraint.md delete mode 100644 docs-devsite/firestore_lite.querylimitconstraint.md delete mode 100644 docs-devsite/firestore_lite.queryorderbyconstraint.md delete mode 100644 docs-devsite/firestore_lite.querysnapshot.md delete mode 100644 docs-devsite/firestore_lite.querystartatconstraint.md delete mode 100644 docs-devsite/firestore_lite.settings.md delete mode 100644 docs-devsite/firestore_lite.timestamp.md delete mode 100644 docs-devsite/firestore_lite.transaction.md delete mode 100644 docs-devsite/firestore_lite.transactionoptions.md delete mode 100644 docs-devsite/firestore_lite.writebatch.md delete mode 100644 docs-devsite/functions.functions.md delete mode 100644 docs-devsite/functions.functionserror.md delete mode 100644 docs-devsite/functions.httpscallableoptions.md delete mode 100644 docs-devsite/functions.httpscallableresult.md delete mode 100644 docs-devsite/functions.md delete mode 100644 docs-devsite/index.md delete mode 100644 docs-devsite/installations.installations.md delete mode 100644 docs-devsite/installations.md delete mode 100644 docs-devsite/messaging.md delete mode 100644 docs-devsite/messaging_.fcmoptions.md delete mode 100644 docs-devsite/messaging_.gettokenoptions.md delete mode 100644 docs-devsite/messaging_.md delete mode 100644 docs-devsite/messaging_.messagepayload.md delete mode 100644 docs-devsite/messaging_.messaging.md delete mode 100644 docs-devsite/messaging_.notificationpayload.md delete mode 100644 docs-devsite/messaging_sw.fcmoptions.md delete mode 100644 docs-devsite/messaging_sw.gettokenoptions.md delete mode 100644 docs-devsite/messaging_sw.md delete mode 100644 docs-devsite/messaging_sw.messagepayload.md delete mode 100644 docs-devsite/messaging_sw.messaging.md delete mode 100644 docs-devsite/messaging_sw.notificationpayload.md delete mode 100644 docs-devsite/performance.firebaseperformance.md delete mode 100644 docs-devsite/performance.md delete mode 100644 docs-devsite/performance.performancesettings.md delete mode 100644 docs-devsite/performance.performancetrace.md delete mode 100644 docs-devsite/remote-config.md delete mode 100644 docs-devsite/remote-config.remoteconfig.md delete mode 100644 docs-devsite/remote-config.remoteconfigsettings.md delete mode 100644 docs-devsite/remote-config.value.md delete mode 100644 docs-devsite/storage.firebasestorage.md delete mode 100644 docs-devsite/storage.fullmetadata.md delete mode 100644 docs-devsite/storage.listoptions.md delete mode 100644 docs-devsite/storage.listresult.md delete mode 100644 docs-devsite/storage.md delete mode 100644 docs-devsite/storage.settablemetadata.md delete mode 100644 docs-devsite/storage.storageerror.md delete mode 100644 docs-devsite/storage.storageobserver.md delete mode 100644 docs-devsite/storage.storagereference.md delete mode 100644 docs-devsite/storage.uploadmetadata.md delete mode 100644 docs-devsite/storage.uploadresult.md delete mode 100644 docs-devsite/storage.uploadtask.md delete mode 100644 docs-devsite/storage.uploadtasksnapshot.md diff --git a/docs-devsite/analytics.analytics.md b/docs-devsite/analytics.analytics.md deleted file mode 100644 index dcf0038f2d9..00000000000 --- a/docs-devsite/analytics.analytics.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Analytics interface -An instance of Firebase Analytics. - -Signature: - -```typescript -export interface Analytics -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [app](./analytics.analytics.md#analyticsapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this [Analytics](./analytics.analytics.md#analytics_interface) instance is associated with. | - -## Analytics.app - -The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this [Analytics](./analytics.analytics.md#analytics_interface) instance is associated with. - -Signature: - -```typescript -app: FirebaseApp; -``` diff --git a/docs-devsite/analytics.analyticscalloptions.md b/docs-devsite/analytics.analyticscalloptions.md deleted file mode 100644 index d89863bcfa6..00000000000 --- a/docs-devsite/analytics.analyticscalloptions.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AnalyticsCallOptions interface -Additional options that can be passed to Analytics method calls such as `logEvent`, etc. - -Signature: - -```typescript -export interface AnalyticsCallOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [global](./analytics.analyticscalloptions.md#analyticscalloptionsglobal) | boolean | If true, this config or event call applies globally to all Google Analytics properties on the page. | - -## AnalyticsCallOptions.global - -If true, this config or event call applies globally to all Google Analytics properties on the page. - -Signature: - -```typescript -global: boolean; -``` diff --git a/docs-devsite/analytics.analyticssettings.md b/docs-devsite/analytics.analyticssettings.md deleted file mode 100644 index 3ee67d8456d..00000000000 --- a/docs-devsite/analytics.analyticssettings.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AnalyticsSettings interface -[Analytics](./analytics.analytics.md#analytics_interface) instance initialization options. - -Signature: - -```typescript -export interface AnalyticsSettings -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [config](./analytics.analyticssettings.md#analyticssettingsconfig) | [GtagConfigParams](./analytics.gtagconfigparams.md#gtagconfigparams_interface) \| [EventParams](./analytics.eventparams.md#eventparams_interface) | Params to be passed in the initial gtag config call during Firebase Analytics initialization. | - -## AnalyticsSettings.config - -Params to be passed in the initial `gtag` config call during Firebase Analytics initialization. - -Signature: - -```typescript -config?: GtagConfigParams | EventParams; -``` diff --git a/docs-devsite/analytics.consentsettings.md b/docs-devsite/analytics.consentsettings.md deleted file mode 100644 index 975d51d8bc6..00000000000 --- a/docs-devsite/analytics.consentsettings.md +++ /dev/null @@ -1,79 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ConsentSettings interface -Consent status settings for each consent type. For more information, see [the GA4 reference documentation for consent state and consent types](https://developers.google.com/tag-platform/tag-manager/templates/consent-apis). - -Signature: - -```typescript -export interface ConsentSettings -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [ad\_storage](./analytics.consentsettings.md#consentsettingsad_storage) | [ConsentStatusString](./analytics.md#consentstatusstring) | Enables storage, such as cookies, related to advertising | -| [analytics\_storage](./analytics.consentsettings.md#consentsettingsanalytics_storage) | [ConsentStatusString](./analytics.md#consentstatusstring) | Enables storage, such as cookies, related to analytics (for example, visit duration) | -| [functionality\_storage](./analytics.consentsettings.md#consentsettingsfunctionality_storage) | [ConsentStatusString](./analytics.md#consentstatusstring) | Enables storage that supports the functionality of the website or app such as language settings | -| [personalization\_storage](./analytics.consentsettings.md#consentsettingspersonalization_storage) | [ConsentStatusString](./analytics.md#consentstatusstring) | Enables storage related to personalization such as video recommendations | -| [security\_storage](./analytics.consentsettings.md#consentsettingssecurity_storage) | [ConsentStatusString](./analytics.md#consentstatusstring) | Enables storage related to security such as authentication functionality, fraud prevention, and other user protection. | - -## ConsentSettings.ad\_storage - -Enables storage, such as cookies, related to advertising - -Signature: - -```typescript -ad_storage?: ConsentStatusString; -``` - -## ConsentSettings.analytics\_storage - -Enables storage, such as cookies, related to analytics (for example, visit duration) - -Signature: - -```typescript -analytics_storage?: ConsentStatusString; -``` - -## ConsentSettings.functionality\_storage - -Enables storage that supports the functionality of the website or app such as language settings - -Signature: - -```typescript -functionality_storage?: ConsentStatusString; -``` - -## ConsentSettings.personalization\_storage - -Enables storage related to personalization such as video recommendations - -Signature: - -```typescript -personalization_storage?: ConsentStatusString; -``` - -## ConsentSettings.security\_storage - -Enables storage related to security such as authentication functionality, fraud prevention, and other user protection. - -Signature: - -```typescript -security_storage?: ConsentStatusString; -``` diff --git a/docs-devsite/analytics.controlparams.md b/docs-devsite/analytics.controlparams.md deleted file mode 100644 index d7dfea1460c..00000000000 --- a/docs-devsite/analytics.controlparams.md +++ /dev/null @@ -1,60 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ControlParams interface -Standard `gtag.js` control parameters. For more information, see [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export interface ControlParams -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [event\_callback](./analytics.controlparams.md#controlparamsevent_callback) | () => void | | -| [event\_timeout](./analytics.controlparams.md#controlparamsevent_timeout) | number | | -| [groups](./analytics.controlparams.md#controlparamsgroups) | string \| string\[\] | | -| [send\_to](./analytics.controlparams.md#controlparamssend_to) | string \| string\[\] | | - -## ControlParams.event\_callback - -Signature: - -```typescript -event_callback?: () => void; -``` - -## ControlParams.event\_timeout - -Signature: - -```typescript -event_timeout?: number; -``` - -## ControlParams.groups - -Signature: - -```typescript -groups?: string | string[]; -``` - -## ControlParams.send\_to - -Signature: - -```typescript -send_to?: string | string[]; -``` diff --git a/docs-devsite/analytics.customparams.md b/docs-devsite/analytics.customparams.md deleted file mode 100644 index 37ac6964477..00000000000 --- a/docs-devsite/analytics.customparams.md +++ /dev/null @@ -1,19 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# CustomParams interface -Any custom params the user may pass to `gtag`. - -Signature: - -```typescript -export interface CustomParams -``` diff --git a/docs-devsite/analytics.eventparams.md b/docs-devsite/analytics.eventparams.md deleted file mode 100644 index 266b8d3e85e..00000000000 --- a/docs-devsite/analytics.eventparams.md +++ /dev/null @@ -1,316 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# EventParams interface -Standard `gtag.js` event parameters. For more information, see [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export interface EventParams -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [affiliation](./analytics.eventparams.md#eventparamsaffiliation) | string | | -| [checkout\_option](./analytics.eventparams.md#eventparamscheckout_option) | string | | -| [checkout\_step](./analytics.eventparams.md#eventparamscheckout_step) | number | | -| [content\_type](./analytics.eventparams.md#eventparamscontent_type) | string | | -| [coupon](./analytics.eventparams.md#eventparamscoupon) | string | | -| [currency](./analytics.eventparams.md#eventparamscurrency) | string | | -| [description](./analytics.eventparams.md#eventparamsdescription) | string | | -| [event\_category](./analytics.eventparams.md#eventparamsevent_category) | string | | -| [event\_label](./analytics.eventparams.md#eventparamsevent_label) | string | | -| [fatal](./analytics.eventparams.md#eventparamsfatal) | boolean | | -| [firebase\_screen\_class](./analytics.eventparams.md#eventparamsfirebase_screen_class) | string | Firebase-specific. Use to log a screen_class to Firebase Analytics. | -| [firebase\_screen](./analytics.eventparams.md#eventparamsfirebase_screen) | string | Firebase-specific. Use to log a screen_name to Firebase Analytics. | -| [item\_id](./analytics.eventparams.md#eventparamsitem_id) | string | | -| [item\_list\_id](./analytics.eventparams.md#eventparamsitem_list_id) | string | | -| [item\_list\_name](./analytics.eventparams.md#eventparamsitem_list_name) | string | | -| [items](./analytics.eventparams.md#eventparamsitems) | [Item](./analytics.item.md#item_interface)\[\] | | -| [method](./analytics.eventparams.md#eventparamsmethod) | string | | -| [number](./analytics.eventparams.md#eventparamsnumber) | string | | -| [page\_location](./analytics.eventparams.md#eventparamspage_location) | string | | -| [page\_path](./analytics.eventparams.md#eventparamspage_path) | string | | -| [page\_title](./analytics.eventparams.md#eventparamspage_title) | string | | -| [payment\_type](./analytics.eventparams.md#eventparamspayment_type) | string | | -| [promotion\_id](./analytics.eventparams.md#eventparamspromotion_id) | string | | -| [promotion\_name](./analytics.eventparams.md#eventparamspromotion_name) | string | | -| [promotions](./analytics.eventparams.md#eventparamspromotions) | [Promotion](./analytics.promotion.md#promotion_interface)\[\] | | -| [screen\_name](./analytics.eventparams.md#eventparamsscreen_name) | string | | -| [search\_term](./analytics.eventparams.md#eventparamssearch_term) | string | | -| [shipping\_tier](./analytics.eventparams.md#eventparamsshipping_tier) | string | | -| [shipping](./analytics.eventparams.md#eventparamsshipping) | [Currency](./analytics.md#currency) | | -| [tax](./analytics.eventparams.md#eventparamstax) | [Currency](./analytics.md#currency) | | -| [transaction\_id](./analytics.eventparams.md#eventparamstransaction_id) | string | | -| [value](./analytics.eventparams.md#eventparamsvalue) | number | | - -## EventParams.affiliation - -Signature: - -```typescript -affiliation?: string; -``` - -## EventParams.checkout\_option - -Signature: - -```typescript -checkout_option?: string; -``` - -## EventParams.checkout\_step - -Signature: - -```typescript -checkout_step?: number; -``` - -## EventParams.content\_type - -Signature: - -```typescript -content_type?: string; -``` - -## EventParams.coupon - -Signature: - -```typescript -coupon?: string; -``` - -## EventParams.currency - -Signature: - -```typescript -currency?: string; -``` - -## EventParams.description - -Signature: - -```typescript -description?: string; -``` - -## EventParams.event\_category - -Signature: - -```typescript -event_category?: string; -``` - -## EventParams.event\_label - -Signature: - -```typescript -event_label?: string; -``` - -## EventParams.fatal - -Signature: - -```typescript -fatal?: boolean; -``` - -## EventParams.firebase\_screen\_class - -Firebase-specific. Use to log a `screen_class` to Firebase Analytics. - -Signature: - -```typescript -firebase_screen_class?: string; -``` - -## EventParams.firebase\_screen - -Firebase-specific. Use to log a `screen_name` to Firebase Analytics. - -Signature: - -```typescript -firebase_screen?: string; -``` - -## EventParams.item\_id - -Signature: - -```typescript -item_id?: string; -``` - -## EventParams.item\_list\_id - -Signature: - -```typescript -item_list_id?: string; -``` - -## EventParams.item\_list\_name - -Signature: - -```typescript -item_list_name?: string; -``` - -## EventParams.items - -Signature: - -```typescript -items?: Item[]; -``` - -## EventParams.method - -Signature: - -```typescript -method?: string; -``` - -## EventParams.number - -Signature: - -```typescript -number?: string; -``` - -## EventParams.page\_location - -Signature: - -```typescript -page_location?: string; -``` - -## EventParams.page\_path - -Signature: - -```typescript -page_path?: string; -``` - -## EventParams.page\_title - -Signature: - -```typescript -page_title?: string; -``` - -## EventParams.payment\_type - -Signature: - -```typescript -payment_type?: string; -``` - -## EventParams.promotion\_id - -Signature: - -```typescript -promotion_id?: string; -``` - -## EventParams.promotion\_name - -Signature: - -```typescript -promotion_name?: string; -``` - -## EventParams.promotions - -Signature: - -```typescript -promotions?: Promotion[]; -``` - -## EventParams.screen\_name - -Signature: - -```typescript -screen_name?: string; -``` - -## EventParams.search\_term - -Signature: - -```typescript -search_term?: string; -``` - -## EventParams.shipping\_tier - -Signature: - -```typescript -shipping_tier?: string; -``` - -## EventParams.shipping - -Signature: - -```typescript -shipping?: Currency; -``` - -## EventParams.tax - -Signature: - -```typescript -tax?: Currency; -``` - -## EventParams.transaction\_id - -Signature: - -```typescript -transaction_id?: string; -``` - -## EventParams.value - -Signature: - -```typescript -value?: number; -``` diff --git a/docs-devsite/analytics.gtagconfigparams.md b/docs-devsite/analytics.gtagconfigparams.md deleted file mode 100644 index f5138b8b65e..00000000000 --- a/docs-devsite/analytics.gtagconfigparams.md +++ /dev/null @@ -1,134 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# GtagConfigParams interface -A set of common Google Analytics config settings recognized by `gtag.js`. - -Signature: - -```typescript -export interface GtagConfigParams -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [allow\_ad\_personalization\_signals](./analytics.gtagconfigparams.md#gtagconfigparamsallow_ad_personalization_signals) | boolean | If set to false, disables all advertising personalization with gtag.js. See [Disable advertising features](https://developers.google.com/analytics/devguides/collection/ga4/display-features) | -| [allow\_google\_signals](./analytics.gtagconfigparams.md#gtagconfigparamsallow_google_signals) | boolean | If set to false, disables all advertising features with gtag.js. See [Disable advertising features](https://developers.google.com/analytics/devguides/collection/ga4/display-features) | -| [cookie\_domain](./analytics.gtagconfigparams.md#gtagconfigparamscookie_domain) | string | Defaults to auto. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) | -| [cookie\_expires](./analytics.gtagconfigparams.md#gtagconfigparamscookie_expires) | number | Defaults to 63072000 (two years, in seconds). See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) | -| [cookie\_flags](./analytics.gtagconfigparams.md#gtagconfigparamscookie_flags) | string | Appends additional flags to the cookie when set. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) | -| [cookie\_prefix](./analytics.gtagconfigparams.md#gtagconfigparamscookie_prefix) | string | Defaults to _ga. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) | -| [cookie\_update](./analytics.gtagconfigparams.md#gtagconfigparamscookie_update) | boolean | If set to true, will update cookies on each page load. Defaults to true. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) | -| [page\_location](./analytics.gtagconfigparams.md#gtagconfigparamspage_location) | string | The URL of the page. See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view) | -| [page\_title](./analytics.gtagconfigparams.md#gtagconfigparamspage_title) | string | The title of the page. See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view) | -| [send\_page\_view](./analytics.gtagconfigparams.md#gtagconfigparamssend_page_view) | boolean | Whether or not a page view should be sent. If set to true (default), a page view is automatically sent upon initialization of analytics. See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view) | - -## GtagConfigParams.allow\_ad\_personalization\_signals - -If set to false, disables all advertising personalization with `gtag.js`. See [Disable advertising features](https://developers.google.com/analytics/devguides/collection/ga4/display-features) - -Signature: - -```typescript -'allow_ad_personalization_signals'?: boolean; -``` - -## GtagConfigParams.allow\_google\_signals - -If set to false, disables all advertising features with `gtag.js`. See [Disable advertising features](https://developers.google.com/analytics/devguides/collection/ga4/display-features) - -Signature: - -```typescript -'allow_google_signals'?: boolean; -``` - -## GtagConfigParams.cookie\_domain - -Defaults to `auto`. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) - -Signature: - -```typescript -'cookie_domain'?: string; -``` - -## GtagConfigParams.cookie\_expires - -Defaults to 63072000 (two years, in seconds). See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) - -Signature: - -```typescript -'cookie_expires'?: number; -``` - -## GtagConfigParams.cookie\_flags - -Appends additional flags to the cookie when set. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) - -Signature: - -```typescript -'cookie_flags'?: string; -``` - -## GtagConfigParams.cookie\_prefix - -Defaults to `_ga`. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) - -Signature: - -```typescript -'cookie_prefix'?: string; -``` - -## GtagConfigParams.cookie\_update - -If set to true, will update cookies on each page load. Defaults to true. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) - -Signature: - -```typescript -'cookie_update'?: boolean; -``` - -## GtagConfigParams.page\_location - -The URL of the page. See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view) - -Signature: - -```typescript -'page_location'?: string; -``` - -## GtagConfigParams.page\_title - -The title of the page. See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view) - -Signature: - -```typescript -'page_title'?: string; -``` - -## GtagConfigParams.send\_page\_view - -Whether or not a page view should be sent. If set to true (default), a page view is automatically sent upon initialization of analytics. See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view) - -Signature: - -```typescript -'send_page_view'?: boolean; -``` diff --git a/docs-devsite/analytics.item.md b/docs-devsite/analytics.item.md deleted file mode 100644 index 5c853918edb..00000000000 --- a/docs-devsite/analytics.item.md +++ /dev/null @@ -1,278 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Item interface -Standard Google Analytics `Item` type. - -Signature: - -```typescript -export interface Item -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [affiliation](./analytics.item.md#itemaffiliation) | string | | -| [brand](./analytics.item.md#itembrand) | string | | -| [category](./analytics.item.md#itemcategory) | string | | -| [coupon](./analytics.item.md#itemcoupon) | string | | -| [creative\_name](./analytics.item.md#itemcreative_name) | string | | -| [creative\_slot](./analytics.item.md#itemcreative_slot) | string | | -| [discount](./analytics.item.md#itemdiscount) | [Currency](./analytics.md#currency) | | -| [id](./analytics.item.md#itemid) | string | | -| [index](./analytics.item.md#itemindex) | number | | -| [item\_brand](./analytics.item.md#itemitem_brand) | string | | -| [item\_category](./analytics.item.md#itemitem_category) | string | | -| [item\_category2](./analytics.item.md#itemitem_category2) | string | | -| [item\_category3](./analytics.item.md#itemitem_category3) | string | | -| [item\_category4](./analytics.item.md#itemitem_category4) | string | | -| [item\_category5](./analytics.item.md#itemitem_category5) | string | | -| [item\_id](./analytics.item.md#itemitem_id) | string | | -| [item\_list\_id](./analytics.item.md#itemitem_list_id) | string | | -| [item\_list\_name](./analytics.item.md#itemitem_list_name) | string | | -| [item\_name](./analytics.item.md#itemitem_name) | string | | -| [item\_variant](./analytics.item.md#itemitem_variant) | string | | -| [location\_id](./analytics.item.md#itemlocation_id) | string | | -| [name](./analytics.item.md#itemname) | string | | -| [price](./analytics.item.md#itemprice) | [Currency](./analytics.md#currency) | | -| [promotion\_id](./analytics.item.md#itempromotion_id) | string | | -| [promotion\_name](./analytics.item.md#itempromotion_name) | string | | -| [quantity](./analytics.item.md#itemquantity) | number | | - -## Item.affiliation - -Signature: - -```typescript -affiliation?: string; -``` - -## Item.brand - -> Warning: This API is now obsolete. -> -> Use item\_brand instead. -> - -Signature: - -```typescript -brand?: string; -``` - -## Item.category - -> Warning: This API is now obsolete. -> -> Use item\_category instead. -> - -Signature: - -```typescript -category?: string; -``` - -## Item.coupon - -Signature: - -```typescript -coupon?: string; -``` - -## Item.creative\_name - -Signature: - -```typescript -creative_name?: string; -``` - -## Item.creative\_slot - -Signature: - -```typescript -creative_slot?: string; -``` - -## Item.discount - -Signature: - -```typescript -discount?: Currency; -``` - -## Item.id - -> Warning: This API is now obsolete. -> -> Use item\_id instead. -> - -Signature: - -```typescript -id?: string; -``` - -## Item.index - -Signature: - -```typescript -index?: number; -``` - -## Item.item\_brand - -Signature: - -```typescript -item_brand?: string; -``` - -## Item.item\_category - -Signature: - -```typescript -item_category?: string; -``` - -## Item.item\_category2 - -Signature: - -```typescript -item_category2?: string; -``` - -## Item.item\_category3 - -Signature: - -```typescript -item_category3?: string; -``` - -## Item.item\_category4 - -Signature: - -```typescript -item_category4?: string; -``` - -## Item.item\_category5 - -Signature: - -```typescript -item_category5?: string; -``` - -## Item.item\_id - -Signature: - -```typescript -item_id?: string; -``` - -## Item.item\_list\_id - -Signature: - -```typescript -item_list_id?: string; -``` - -## Item.item\_list\_name - -Signature: - -```typescript -item_list_name?: string; -``` - -## Item.item\_name - -Signature: - -```typescript -item_name?: string; -``` - -## Item.item\_variant - -Signature: - -```typescript -item_variant?: string; -``` - -## Item.location\_id - -Signature: - -```typescript -location_id?: string; -``` - -## Item.name - -> Warning: This API is now obsolete. -> -> Use item\_name instead. -> - -Signature: - -```typescript -name?: string; -``` - -## Item.price - -Signature: - -```typescript -price?: Currency; -``` - -## Item.promotion\_id - -Signature: - -```typescript -promotion_id?: string; -``` - -## Item.promotion\_name - -Signature: - -```typescript -promotion_name?: string; -``` - -## Item.quantity - -Signature: - -```typescript -quantity?: number; -``` diff --git a/docs-devsite/analytics.md b/docs-devsite/analytics.md deleted file mode 100644 index bd6e4b69351..00000000000 --- a/docs-devsite/analytics.md +++ /dev/null @@ -1,991 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# analytics package -Firebase Analytics - -## Functions - -| Function | Description | -| --- | --- | -| function(app...) | -| [getAnalytics(app)](./analytics.md#getanalytics) | Returns an [Analytics](./analytics.analytics.md#analytics_interface) instance for the given app. | -| [initializeAnalytics(app, options)](./analytics.md#initializeanalytics) | Returns an [Analytics](./analytics.analytics.md#analytics_interface) instance for the given app. | -| function(analyticsInstance...) | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.See [Track Screenviews](https://firebase.google.com/docs/analytics/screenviews). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.See [Measure exceptions](https://developers.google.com/analytics/devguides/collection/ga4/exceptions). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view). | -| [setAnalyticsCollectionEnabled(analyticsInstance, enabled)](./analytics.md#setanalyticscollectionenabled) | Sets whether Google Analytics collection is enabled for this app on this device. Sets global window['ga-disable-analyticsId'] = true; | -| [setCurrentScreen(analyticsInstance, screenName, options)](./analytics.md#setcurrentscreen) | Use gtag config command to set screen_name. | -| [setUserId(analyticsInstance, id, options)](./analytics.md#setuserid) | Use gtag config command to set user_id. | -| [setUserProperties(analyticsInstance, properties, options)](./analytics.md#setuserproperties) | Use gtag config command to set all params specified. | -| function() | -| [isSupported()](./analytics.md#issupported) | This is a public static method provided to users that wraps four different checks:1. Check if it's not a browser extension environment. 2. Check if cookies are enabled in current browser. 3. Check if IndexedDB is supported by the browser environment. 4. Check if the current browser context is valid for using IndexedDB.open(). | -| function(consentSettings...) | -| [setConsent(consentSettings)](./analytics.md#setconsent) | Sets the applicable end user consent state for this web app across all gtag references once Firebase Analytics is initialized.Use the [ConsentSettings](./analytics.consentsettings.md#consentsettings_interface) to specify individual consent type values. By default consent types are set to "granted". | -| function(customParams...) | -| [setDefaultEventParameters(customParams)](./analytics.md#setdefaulteventparameters) | Adds data that will be set on every event logged from the SDK, including automatic ones. With gtag's "set" command, the values passed persist on the current page and are passed with all subsequent events. | -| function(options...) | -| [settings(options)](./analytics.md#settings) | Configures Firebase Analytics to use custom gtag or dataLayer names. Intended to be used if gtag.js script has been installed on this page independently of Firebase Analytics, and is using non-default names for either the gtag function or for dataLayer. Must be called before calling getAnalytics() or it won't have any effect. | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [Analytics](./analytics.analytics.md#analytics_interface) | An instance of Firebase Analytics. | -| [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | Additional options that can be passed to Analytics method calls such as logEvent, etc. | -| [AnalyticsSettings](./analytics.analyticssettings.md#analyticssettings_interface) | [Analytics](./analytics.analytics.md#analytics_interface) instance initialization options. | -| [ConsentSettings](./analytics.consentsettings.md#consentsettings_interface) | Consent status settings for each consent type. For more information, see [the GA4 reference documentation for consent state and consent types](https://developers.google.com/tag-platform/tag-manager/templates/consent-apis). | -| [ControlParams](./analytics.controlparams.md#controlparams_interface) | Standard gtag.js control parameters. For more information, see [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [CustomParams](./analytics.customparams.md#customparams_interface) | Any custom params the user may pass to gtag. | -| [EventParams](./analytics.eventparams.md#eventparams_interface) | Standard gtag.js event parameters. For more information, see [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | -| [GtagConfigParams](./analytics.gtagconfigparams.md#gtagconfigparams_interface) | A set of common Google Analytics config settings recognized by gtag.js. | -| [Item](./analytics.item.md#item_interface) | Standard Google Analytics Item type. | -| [Promotion](./analytics.promotion.md#promotion_interface) | Field previously used by some Google Analytics events. | -| [SettingsOptions](./analytics.settingsoptions.md#settingsoptions_interface) | Specifies custom options for your Firebase Analytics instance. You must set these before initializing firebase.analytics(). | - -## Type Aliases - -| Type Alias | Description | -| --- | --- | -| [ConsentStatusString](./analytics.md#consentstatusstring) | Whether a particular consent type has been granted or denied. | -| [Currency](./analytics.md#currency) | Standard Google Analytics currency type. | -| [CustomEventName](./analytics.md#customeventname) | Any custom event name string not in the standard list of recommended event names. | -| [EventNameString](./analytics.md#eventnamestring) | Type for standard Google Analytics event names. logEvent also accepts any custom string and interprets it as a custom event name. | - -## getAnalytics() - -Returns an [Analytics](./analytics.analytics.md#analytics_interface) instance for the given app. - -Signature: - -```typescript -export declare function getAnalytics(app?: FirebaseApp): Analytics; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to use. | - -Returns: - -[Analytics](./analytics.analytics.md#analytics_interface) - -## initializeAnalytics() - -Returns an [Analytics](./analytics.analytics.md#analytics_interface) instance for the given app. - -Signature: - -```typescript -export declare function initializeAnalytics(app: FirebaseApp, options?: AnalyticsSettings): Analytics; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to use. | -| options | [AnalyticsSettings](./analytics.analyticssettings.md#analyticssettings_interface) | | - -Returns: - -[Analytics](./analytics.analytics.md#analytics_interface) - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'add_payment_info', eventParams?: { - coupon?: EventParams['coupon']; - currency?: EventParams['currency']; - items?: EventParams['items']; - payment_type?: EventParams['payment_type']; - value?: EventParams['value']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'add\_payment\_info' | | -| eventParams | { coupon?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['coupon'\]; currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; payment\_type?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['payment\_type'\]; value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'purchase' | 'refund', eventParams?: { - value?: EventParams['value']; - currency?: EventParams['currency']; - transaction_id: EventParams['transaction_id']; - tax?: EventParams['tax']; - shipping?: EventParams['shipping']; - items?: EventParams['items']; - coupon?: EventParams['coupon']; - affiliation?: EventParams['affiliation']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'purchase' \| 'refund' | | -| eventParams | { value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; transaction\_id: [EventParams](./analytics.eventparams.md#eventparams_interface)\['transaction\_id'\]; tax?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['tax'\]; shipping?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['shipping'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; coupon?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['coupon'\]; affiliation?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['affiliation'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -See [Track Screenviews](https://firebase.google.com/docs/analytics/screenviews). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'screen_view', eventParams?: { - firebase_screen: EventParams['firebase_screen']; - firebase_screen_class: EventParams['firebase_screen_class']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'screen\_view' | | -| eventParams | { firebase\_screen: [EventParams](./analytics.eventparams.md#eventparams_interface)\['firebase\_screen'\]; firebase\_screen\_class: [EventParams](./analytics.eventparams.md#eventparams_interface)\['firebase\_screen\_class'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'search' | 'view_search_results', eventParams?: { - search_term?: EventParams['search_term']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'search' \| 'view\_search\_results' | | -| eventParams | { search\_term?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['search\_term'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'select_content', eventParams?: { - content_type?: EventParams['content_type']; - item_id?: EventParams['item_id']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'select\_content' | | -| eventParams | { content\_type?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['content\_type'\]; item\_id?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['item\_id'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'select_item', eventParams?: { - items?: EventParams['items']; - item_list_name?: EventParams['item_list_name']; - item_list_id?: EventParams['item_list_id']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'select\_item' | | -| eventParams | { items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; item\_list\_name?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['item\_list\_name'\]; item\_list\_id?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['item\_list\_id'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'select_promotion' | 'view_promotion', eventParams?: { - items?: EventParams['items']; - promotion_id?: EventParams['promotion_id']; - promotion_name?: EventParams['promotion_name']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'select\_promotion' \| 'view\_promotion' | | -| eventParams | { items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; promotion\_id?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['promotion\_id'\]; promotion\_name?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['promotion\_name'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'set_checkout_option', eventParams?: { - checkout_step?: EventParams['checkout_step']; - checkout_option?: EventParams['checkout_option']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'set\_checkout\_option' | | -| eventParams | { checkout\_step?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['checkout\_step'\]; checkout\_option?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['checkout\_option'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'share', eventParams?: { - method?: EventParams['method']; - content_type?: EventParams['content_type']; - item_id?: EventParams['item_id']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'share' | | -| eventParams | { method?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['method'\]; content\_type?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['content\_type'\]; item\_id?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['item\_id'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'sign_up', eventParams?: { - method?: EventParams['method']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'sign\_up' | | -| eventParams | { method?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['method'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'timing_complete', eventParams?: { - name: string; - value: number; - event_category?: string; - event_label?: string; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'timing\_complete' | | -| eventParams | { name: string; value: number; event\_category?: string; event\_label?: string; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'add_shipping_info', eventParams?: { - coupon?: EventParams['coupon']; - currency?: EventParams['currency']; - items?: EventParams['items']; - shipping_tier?: EventParams['shipping_tier']; - value?: EventParams['value']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'add\_shipping\_info' | | -| eventParams | { coupon?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['coupon'\]; currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; shipping\_tier?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['shipping\_tier'\]; value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'view_cart' | 'view_item', eventParams?: { - currency?: EventParams['currency']; - items?: EventParams['items']; - value?: EventParams['value']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'view\_cart' \| 'view\_item' | | -| eventParams | { currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'view_item_list', eventParams?: { - items?: EventParams['items']; - item_list_name?: EventParams['item_list_name']; - item_list_id?: EventParams['item_list_id']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'view\_item\_list' | | -| eventParams | { items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; item\_list\_name?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['item\_list\_name'\]; item\_list\_id?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['item\_list\_id'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: CustomEventName, eventParams?: { - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | [CustomEventName](./analytics.md#customeventname)<T> | | -| eventParams | { \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'add_to_cart' | 'add_to_wishlist' | 'remove_from_cart', eventParams?: { - currency?: EventParams['currency']; - value?: EventParams['value']; - items?: EventParams['items']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'add\_to\_cart' \| 'add\_to\_wishlist' \| 'remove\_from\_cart' | | -| eventParams | { currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'begin_checkout', eventParams?: { - currency?: EventParams['currency']; - coupon?: EventParams['coupon']; - value?: EventParams['value']; - items?: EventParams['items']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'begin\_checkout' | | -| eventParams | { currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; coupon?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['coupon'\]; value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'checkout_progress', eventParams?: { - currency?: EventParams['currency']; - coupon?: EventParams['coupon']; - value?: EventParams['value']; - items?: EventParams['items']; - checkout_step?: EventParams['checkout_step']; - checkout_option?: EventParams['checkout_option']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'checkout\_progress' | | -| eventParams | { currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; coupon?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['coupon'\]; value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; checkout\_step?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['checkout\_step'\]; checkout\_option?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['checkout\_option'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -See [Measure exceptions](https://developers.google.com/analytics/devguides/collection/ga4/exceptions). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'exception', eventParams?: { - description?: EventParams['description']; - fatal?: EventParams['fatal']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'exception' | | -| eventParams | { description?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['description'\]; fatal?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['fatal'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'generate_lead', eventParams?: { - value?: EventParams['value']; - currency?: EventParams['currency']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'generate\_lead' | | -| eventParams | { value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'login', eventParams?: { - method?: EventParams['method']; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'login' | | -| eventParams | { method?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['method'\]; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## logEvent() - -Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. - -See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view). - -Signature: - -```typescript -export declare function logEvent(analyticsInstance: Analytics, eventName: 'page_view', eventParams?: { - page_title?: string; - page_location?: string; - page_path?: string; - [key: string]: any; -}, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| eventName | 'page\_view' | | -| eventParams | { page\_title?: string; page\_location?: string; page\_path?: string; \[key: string\]: any; } | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## setAnalyticsCollectionEnabled() - -Sets whether Google Analytics collection is enabled for this app on this device. Sets global `window['ga-disable-analyticsId'] = true;` - -Signature: - -```typescript -export declare function setAnalyticsCollectionEnabled(analyticsInstance: Analytics, enabled: boolean): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | The [Analytics](./analytics.analytics.md#analytics_interface) instance. | -| enabled | boolean | If true, enables collection, if false, disables it. | - -Returns: - -void - -## setCurrentScreen() - -> Warning: This API is now obsolete. -> -> Use with `eventName` as 'screen\_view' and add relevant `eventParams`. See [Track Screenviews](https://firebase.google.com/docs/analytics/screenviews). -> - -Use gtag `config` command to set `screen_name`. - -Signature: - -```typescript -export declare function setCurrentScreen(analyticsInstance: Analytics, screenName: string, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | The [Analytics](./analytics.analytics.md#analytics_interface) instance. | -| screenName | string | Screen name to set. | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## setUserId() - -Use gtag `config` command to set `user_id`. - -Signature: - -```typescript -export declare function setUserId(analyticsInstance: Analytics, id: string | null, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | The [Analytics](./analytics.analytics.md#analytics_interface) instance. | -| id | string \| null | User ID to set. | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## setUserProperties() - -Use gtag `config` command to set all params specified. - -Signature: - -```typescript -export declare function setUserProperties(analyticsInstance: Analytics, properties: CustomParams, options?: AnalyticsCallOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | -| properties | [CustomParams](./analytics.customparams.md#customparams_interface) | | -| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | - -Returns: - -void - -## isSupported() - -This is a public static method provided to users that wraps four different checks: - -1. Check if it's not a browser extension environment. 2. Check if cookies are enabled in current browser. 3. Check if IndexedDB is supported by the browser environment. 4. Check if the current browser context is valid for using `IndexedDB.open()`. - -Signature: - -```typescript -export declare function isSupported(): Promise; -``` -Returns: - -Promise<boolean> - -## setConsent() - -Sets the applicable end user consent state for this web app across all gtag references once Firebase Analytics is initialized. - -Use the [ConsentSettings](./analytics.consentsettings.md#consentsettings_interface) to specify individual consent type values. By default consent types are set to "granted". - -Signature: - -```typescript -export declare function setConsent(consentSettings: ConsentSettings): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| consentSettings | [ConsentSettings](./analytics.consentsettings.md#consentsettings_interface) | Maps the applicable end user consent state for gtag.js. | - -Returns: - -void - -## setDefaultEventParameters() - -Adds data that will be set on every event logged from the SDK, including automatic ones. With gtag's "set" command, the values passed persist on the current page and are passed with all subsequent events. - -Signature: - -```typescript -export declare function setDefaultEventParameters(customParams: CustomParams): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| customParams | [CustomParams](./analytics.customparams.md#customparams_interface) | Any custom params the user may pass to gtag.js. | - -Returns: - -void - -## settings() - -Configures Firebase Analytics to use custom `gtag` or `dataLayer` names. Intended to be used if `gtag.js` script has been installed on this page independently of Firebase Analytics, and is using non-default names for either the `gtag` function or for `dataLayer`. Must be called before calling `getAnalytics()` or it won't have any effect. - -Signature: - -```typescript -export declare function settings(options: SettingsOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| options | [SettingsOptions](./analytics.settingsoptions.md#settingsoptions_interface) | Custom gtag and dataLayer names. | - -Returns: - -void - -## ConsentStatusString - -Whether a particular consent type has been granted or denied. - -Signature: - -```typescript -export declare type ConsentStatusString = 'granted' | 'denied'; -``` - -## Currency - -Standard Google Analytics currency type. - -Signature: - -```typescript -export declare type Currency = string | number; -``` - -## CustomEventName - -Any custom event name string not in the standard list of recommended event names. - -Signature: - -```typescript -export declare type CustomEventName = T extends EventNameString ? never : T; -``` - -## EventNameString - -Type for standard Google Analytics event names. `logEvent` also accepts any custom string and interprets it as a custom event name. - -Signature: - -```typescript -export declare type EventNameString = 'add_payment_info' | 'add_shipping_info' | 'add_to_cart' | 'add_to_wishlist' | 'begin_checkout' | 'checkout_progress' | 'exception' | 'generate_lead' | 'login' | 'page_view' | 'purchase' | 'refund' | 'remove_from_cart' | 'screen_view' | 'search' | 'select_content' | 'select_item' | 'select_promotion' | 'set_checkout_option' | 'share' | 'sign_up' | 'timing_complete' | 'view_cart' | 'view_item' | 'view_item_list' | 'view_promotion' | 'view_search_results'; -``` diff --git a/docs-devsite/analytics.promotion.md b/docs-devsite/analytics.promotion.md deleted file mode 100644 index 7e29e0335e4..00000000000 --- a/docs-devsite/analytics.promotion.md +++ /dev/null @@ -1,65 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Promotion interface -> Warning: This API is now obsolete. -> -> Use `Item` instead. -> - -Field previously used by some Google Analytics events. - -Signature: - -```typescript -export interface Promotion -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [creative\_name](./analytics.promotion.md#promotioncreative_name) | string | | -| [creative\_slot](./analytics.promotion.md#promotioncreative_slot) | string | | -| [id](./analytics.promotion.md#promotionid) | string | | -| [name](./analytics.promotion.md#promotionname) | string | | - -## Promotion.creative\_name - -Signature: - -```typescript -creative_name?: string; -``` - -## Promotion.creative\_slot - -Signature: - -```typescript -creative_slot?: string; -``` - -## Promotion.id - -Signature: - -```typescript -id?: string; -``` - -## Promotion.name - -Signature: - -```typescript -name?: string; -``` diff --git a/docs-devsite/analytics.settingsoptions.md b/docs-devsite/analytics.settingsoptions.md deleted file mode 100644 index e43152074d0..00000000000 --- a/docs-devsite/analytics.settingsoptions.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# SettingsOptions interface -Specifies custom options for your Firebase Analytics instance. You must set these before initializing `firebase.analytics()`. - -Signature: - -```typescript -export interface SettingsOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [dataLayerName](./analytics.settingsoptions.md#settingsoptionsdatalayername) | string | Sets custom name for dataLayer array used by gtag.js. | -| [gtagName](./analytics.settingsoptions.md#settingsoptionsgtagname) | string | Sets custom name for gtag function. | - -## SettingsOptions.dataLayerName - -Sets custom name for `dataLayer` array used by `gtag.js`. - -Signature: - -```typescript -dataLayerName?: string; -``` - -## SettingsOptions.gtagName - -Sets custom name for `gtag` function. - -Signature: - -```typescript -gtagName?: string; -``` diff --git a/docs-devsite/app-check.appcheck.md b/docs-devsite/app-check.appcheck.md deleted file mode 100644 index a4cb809924d..00000000000 --- a/docs-devsite/app-check.appcheck.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AppCheck interface -The Firebase App Check service interface. - -Signature: - -```typescript -export interface AppCheck -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [app](./app-check.appcheck.md#appcheckapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this AppCheck instance is associated with. | - -## AppCheck.app - -The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `AppCheck` instance is associated with. - -Signature: - -```typescript -app: FirebaseApp; -``` diff --git a/docs-devsite/app-check.appcheckoptions.md b/docs-devsite/app-check.appcheckoptions.md deleted file mode 100644 index 4d3630faa65..00000000000 --- a/docs-devsite/app-check.appcheckoptions.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AppCheckOptions interface -Options for App Check initialization. - -Signature: - -```typescript -export interface AppCheckOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [isTokenAutoRefreshEnabled](./app-check.appcheckoptions.md#appcheckoptionsistokenautorefreshenabled) | boolean | If set to true, enables automatic background refresh of App Check token. | -| [provider](./app-check.appcheckoptions.md#appcheckoptionsprovider) | [CustomProvider](./app-check.customprovider.md#customprovider_class) \| [ReCaptchaV3Provider](./app-check.recaptchav3provider.md#recaptchav3provider_class) \| [ReCaptchaEnterpriseProvider](./app-check.recaptchaenterpriseprovider.md#recaptchaenterpriseprovider_class) | A reCAPTCHA V3 provider, reCAPTCHA Enterprise provider, or custom provider. | - -## AppCheckOptions.isTokenAutoRefreshEnabled - -If set to true, enables automatic background refresh of App Check token. - -Signature: - -```typescript -isTokenAutoRefreshEnabled?: boolean; -``` - -## AppCheckOptions.provider - -A reCAPTCHA V3 provider, reCAPTCHA Enterprise provider, or custom provider. - -Signature: - -```typescript -provider: CustomProvider | ReCaptchaV3Provider | ReCaptchaEnterpriseProvider; -``` diff --git a/docs-devsite/app-check.appchecktoken.md b/docs-devsite/app-check.appchecktoken.md deleted file mode 100644 index 9cb71d78bbb..00000000000 --- a/docs-devsite/app-check.appchecktoken.md +++ /dev/null @@ -1,44 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AppCheckToken interface -The token returned from an App Check provider. - -Signature: - -```typescript -export interface AppCheckToken -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [expireTimeMillis](./app-check.appchecktoken.md#appchecktokenexpiretimemillis) | number | The local timestamp after which the token will expire. | -| [token](./app-check.appchecktoken.md#appchecktokentoken) | string | | - -## AppCheckToken.expireTimeMillis - -The local timestamp after which the token will expire. - -Signature: - -```typescript -readonly expireTimeMillis: number; -``` - -## AppCheckToken.token - -Signature: - -```typescript -readonly token: string; -``` diff --git a/docs-devsite/app-check.appchecktokenresult.md b/docs-devsite/app-check.appchecktokenresult.md deleted file mode 100644 index 185d60992c1..00000000000 --- a/docs-devsite/app-check.appchecktokenresult.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AppCheckTokenResult interface -Result returned by `getToken()`. - -Signature: - -```typescript -export interface AppCheckTokenResult -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [token](./app-check.appchecktokenresult.md#appchecktokenresulttoken) | string | The token string in JWT format. | - -## AppCheckTokenResult.token - -The token string in JWT format. - -Signature: - -```typescript -readonly token: string; -``` diff --git a/docs-devsite/app-check.customprovider.md b/docs-devsite/app-check.customprovider.md deleted file mode 100644 index e00da1d7897..00000000000 --- a/docs-devsite/app-check.customprovider.md +++ /dev/null @@ -1,43 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# CustomProvider class -Custom provider class. - -Signature: - -```typescript -export declare class CustomProvider implements AppCheckProvider -``` -Implements: AppCheckProvider - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(\_customProviderOptions)](./app-check.customprovider.md#customproviderconstructor) | | Constructs a new instance of the CustomProvider class | - -## CustomProvider.(constructor) - -Constructs a new instance of the `CustomProvider` class - -Signature: - -```typescript -constructor(_customProviderOptions: CustomProviderOptions); -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| \_customProviderOptions | [CustomProviderOptions](./app-check.customprovideroptions.md#customprovideroptions_interface) | | - diff --git a/docs-devsite/app-check.customprovideroptions.md b/docs-devsite/app-check.customprovideroptions.md deleted file mode 100644 index c122e0476dd..00000000000 --- a/docs-devsite/app-check.customprovideroptions.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# CustomProviderOptions interface -Options when creating a [CustomProvider](./app-check.customprovider.md#customprovider_class). - -Signature: - -```typescript -export interface CustomProviderOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [getToken](./app-check.customprovideroptions.md#customprovideroptionsgettoken) | () => Promise<[AppCheckToken](./app-check.appchecktoken.md#appchecktoken_interface)> | Function to get an App Check token through a custom provider service. | - -## CustomProviderOptions.getToken - -Function to get an App Check token through a custom provider service. - -Signature: - -```typescript -getToken: () => Promise; -``` diff --git a/docs-devsite/app-check.md b/docs-devsite/app-check.md deleted file mode 100644 index b7895a05c96..00000000000 --- a/docs-devsite/app-check.md +++ /dev/null @@ -1,170 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# app-check package -Firebase App Check - -## Functions - -| Function | Description | -| --- | --- | -| function(app...) | -| [initializeAppCheck(app, options)](./app-check.md#initializeappcheck) | Activate App Check for the given app. Can be called only once per app. | -| function(appCheckInstance...) | -| [getToken(appCheckInstance, forceRefresh)](./app-check.md#gettoken) | Get the current App Check token. Attaches to the most recent in-flight request if one is present. Returns null if no token is present and no token requests are in-flight. | -| [onTokenChanged(appCheckInstance, observer)](./app-check.md#ontokenchanged) | Registers a listener to changes in the token state. There can be more than one listener registered at the same time for one or more App Check instances. The listeners call back on the UI thread whenever the current token associated with this App Check instance changes. | -| [onTokenChanged(appCheckInstance, onNext, onError, onCompletion)](./app-check.md#ontokenchanged) | Registers a listener to changes in the token state. There can be more than one listener registered at the same time for one or more App Check instances. The listeners call back on the UI thread whenever the current token associated with this App Check instance changes. | -| [setTokenAutoRefreshEnabled(appCheckInstance, isTokenAutoRefreshEnabled)](./app-check.md#settokenautorefreshenabled) | Set whether App Check will automatically refresh tokens as needed. | - -## Classes - -| Class | Description | -| --- | --- | -| [CustomProvider](./app-check.customprovider.md#customprovider_class) | Custom provider class. | -| [ReCaptchaEnterpriseProvider](./app-check.recaptchaenterpriseprovider.md#recaptchaenterpriseprovider_class) | App Check provider that can obtain a reCAPTCHA Enterprise token and exchange it for an App Check token. | -| [ReCaptchaV3Provider](./app-check.recaptchav3provider.md#recaptchav3provider_class) | App Check provider that can obtain a reCAPTCHA V3 token and exchange it for an App Check token. | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [AppCheck](./app-check.appcheck.md#appcheck_interface) | The Firebase App Check service interface. | -| [AppCheckOptions](./app-check.appcheckoptions.md#appcheckoptions_interface) | Options for App Check initialization. | -| [AppCheckToken](./app-check.appchecktoken.md#appchecktoken_interface) | The token returned from an App Check provider. | -| [AppCheckTokenResult](./app-check.appchecktokenresult.md#appchecktokenresult_interface) | Result returned by getToken(). | -| [CustomProviderOptions](./app-check.customprovideroptions.md#customprovideroptions_interface) | Options when creating a [CustomProvider](./app-check.customprovider.md#customprovider_class). | - -## Type Aliases - -| Type Alias | Description | -| --- | --- | -| [AppCheckTokenListener](./app-check.md#appchecktokenlistener) | A listener that is called whenever the App Check token changes. | - -## initializeAppCheck() - -Activate App Check for the given app. Can be called only once per app. - -Signature: - -```typescript -export declare function initializeAppCheck(app: FirebaseApp | undefined, options: AppCheckOptions): AppCheck; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) \| undefined | the [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to activate App Check for | -| options | [AppCheckOptions](./app-check.appcheckoptions.md#appcheckoptions_interface) | App Check initialization options | - -Returns: - -[AppCheck](./app-check.appcheck.md#appcheck_interface) - -## getToken() - -Get the current App Check token. Attaches to the most recent in-flight request if one is present. Returns null if no token is present and no token requests are in-flight. - -Signature: - -```typescript -export declare function getToken(appCheckInstance: AppCheck, forceRefresh?: boolean): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| appCheckInstance | [AppCheck](./app-check.appcheck.md#appcheck_interface) | The App Check service instance. | -| forceRefresh | boolean | If true, will always try to fetch a fresh token. If false, will use a cached token if found in storage. | - -Returns: - -Promise<[AppCheckTokenResult](./app-check.appchecktokenresult.md#appchecktokenresult_interface)> - -## onTokenChanged() - -Registers a listener to changes in the token state. There can be more than one listener registered at the same time for one or more App Check instances. The listeners call back on the UI thread whenever the current token associated with this App Check instance changes. - -Signature: - -```typescript -export declare function onTokenChanged(appCheckInstance: AppCheck, observer: PartialObserver): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| appCheckInstance | [AppCheck](./app-check.appcheck.md#appcheck_interface) | The App Check service instance. | -| observer | [PartialObserver](./util.md#partialobserver)<[AppCheckTokenResult](./app-check.appchecktokenresult.md#appchecktokenresult_interface)> | An object with next, error, and complete properties. next is called with an [AppCheckTokenResult](./app-check.appchecktokenresult.md#appchecktokenresult_interface) whenever the token changes. error is optional and is called if an error is thrown by the listener (the next function). complete is unused, as the token stream is unending. | - -Returns: - -[Unsubscribe](./util.md#unsubscribe) - -A function that unsubscribes this listener. - -## onTokenChanged() - -Registers a listener to changes in the token state. There can be more than one listener registered at the same time for one or more App Check instances. The listeners call back on the UI thread whenever the current token associated with this App Check instance changes. - -Signature: - -```typescript -export declare function onTokenChanged(appCheckInstance: AppCheck, onNext: (tokenResult: AppCheckTokenResult) => void, onError?: (error: Error) => void, onCompletion?: () => void): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| appCheckInstance | [AppCheck](./app-check.appcheck.md#appcheck_interface) | The App Check service instance. | -| onNext | (tokenResult: [AppCheckTokenResult](./app-check.appchecktokenresult.md#appchecktokenresult_interface)) => void | When the token changes, this function is called with aa [AppCheckTokenResult](./app-check.appchecktokenresult.md#appchecktokenresult_interface). | -| onError | (error: Error) => void | Optional. Called if there is an error thrown by the listener (the onNext function). | -| onCompletion | () => void | Currently unused, as the token stream is unending. | - -Returns: - -[Unsubscribe](./util.md#unsubscribe) - -A function that unsubscribes this listener. - -## setTokenAutoRefreshEnabled() - -Set whether App Check will automatically refresh tokens as needed. - -Signature: - -```typescript -export declare function setTokenAutoRefreshEnabled(appCheckInstance: AppCheck, isTokenAutoRefreshEnabled: boolean): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| appCheckInstance | [AppCheck](./app-check.appcheck.md#appcheck_interface) | The App Check service instance. | -| isTokenAutoRefreshEnabled | boolean | If true, the SDK automatically refreshes App Check tokens as needed. This overrides any value set during initializeAppCheck(). | - -Returns: - -void - -## AppCheckTokenListener - -A listener that is called whenever the App Check token changes. - -Signature: - -```typescript -export declare type AppCheckTokenListener = (token: AppCheckTokenResult) => void; -``` diff --git a/docs-devsite/app-check.recaptchaenterpriseprovider.md b/docs-devsite/app-check.recaptchaenterpriseprovider.md deleted file mode 100644 index 21222c24fb9..00000000000 --- a/docs-devsite/app-check.recaptchaenterpriseprovider.md +++ /dev/null @@ -1,43 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ReCaptchaEnterpriseProvider class -App Check provider that can obtain a reCAPTCHA Enterprise token and exchange it for an App Check token. - -Signature: - -```typescript -export declare class ReCaptchaEnterpriseProvider implements AppCheckProvider -``` -Implements: AppCheckProvider - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(\_siteKey)](./app-check.recaptchaenterpriseprovider.md#recaptchaenterpriseproviderconstructor) | | Create a ReCaptchaEnterpriseProvider instance. | - -## ReCaptchaEnterpriseProvider.(constructor) - -Create a ReCaptchaEnterpriseProvider instance. - -Signature: - -```typescript -constructor(_siteKey: string); -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| \_siteKey | string | | - diff --git a/docs-devsite/app-check.recaptchav3provider.md b/docs-devsite/app-check.recaptchav3provider.md deleted file mode 100644 index f2df61a639d..00000000000 --- a/docs-devsite/app-check.recaptchav3provider.md +++ /dev/null @@ -1,43 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ReCaptchaV3Provider class -App Check provider that can obtain a reCAPTCHA V3 token and exchange it for an App Check token. - -Signature: - -```typescript -export declare class ReCaptchaV3Provider implements AppCheckProvider -``` -Implements: AppCheckProvider - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(\_siteKey)](./app-check.recaptchav3provider.md#recaptchav3providerconstructor) | | Create a ReCaptchaV3Provider instance. | - -## ReCaptchaV3Provider.(constructor) - -Create a ReCaptchaV3Provider instance. - -Signature: - -```typescript -constructor(_siteKey: string); -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| \_siteKey | string | | - diff --git a/docs-devsite/app.firebaseapp.md b/docs-devsite/app.firebaseapp.md deleted file mode 100644 index cafbfdd7c54..00000000000 --- a/docs-devsite/app.firebaseapp.md +++ /dev/null @@ -1,91 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FirebaseApp interface -A [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) holds the initialization information for a collection of services. - -Do not call this constructor directly. Instead, use [initializeApp()](./app.md#initializeapp) to create an app. - -Signature: - -```typescript -export interface FirebaseApp -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [automaticDataCollectionEnabled](./app.firebaseapp.md#firebaseappautomaticdatacollectionenabled) | boolean | The settable config flag for GDPR opt-in/opt-out | -| [name](./app.firebaseapp.md#firebaseappname) | string | The (read-only) name for this app.The default app's name is "[DEFAULT]". | -| [options](./app.firebaseapp.md#firebaseappoptions) | [FirebaseOptions](./app.firebaseoptions.md#firebaseoptions_interface) | The (read-only) configuration options for this app. These are the original parameters given in [initializeApp()](./app.md#initializeapp). | - -## FirebaseApp.automaticDataCollectionEnabled - -The settable config flag for GDPR opt-in/opt-out - -Signature: - -```typescript -automaticDataCollectionEnabled: boolean; -``` - -## FirebaseApp.name - -The (read-only) name for this app. - -The default app's name is `"[DEFAULT]"`. - -Signature: - -```typescript -readonly name: string; -``` - -### Example 1 - - -```javascript -// The default app's name is "[DEFAULT]" -const app = initializeApp(defaultAppConfig); -console.log(app.name); // "[DEFAULT]" - -``` - -### Example 2 - - -```javascript -// A named app's name is what you provide to initializeApp() -const otherApp = initializeApp(otherAppConfig, "other"); -console.log(otherApp.name); // "other" - -``` - -## FirebaseApp.options - -The (read-only) configuration options for this app. These are the original parameters given in [initializeApp()](./app.md#initializeapp). - -Signature: - -```typescript -readonly options: FirebaseOptions; -``` - -### Example - - -```javascript -const app = initializeApp(config); -console.log(app.options.databaseURL === config.databaseURL); // true - -``` - diff --git a/docs-devsite/app.firebaseappsettings.md b/docs-devsite/app.firebaseappsettings.md deleted file mode 100644 index 3d9f858e548..00000000000 --- a/docs-devsite/app.firebaseappsettings.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FirebaseAppSettings interface -Configuration options given to [initializeApp()](./app.md#initializeapp) - -Signature: - -```typescript -export interface FirebaseAppSettings -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [automaticDataCollectionEnabled](./app.firebaseappsettings.md#firebaseappsettingsautomaticdatacollectionenabled) | boolean | The settable config flag for GDPR opt-in/opt-out | -| [name](./app.firebaseappsettings.md#firebaseappsettingsname) | string | custom name for the Firebase App. The default value is "[DEFAULT]". | - -## FirebaseAppSettings.automaticDataCollectionEnabled - -The settable config flag for GDPR opt-in/opt-out - -Signature: - -```typescript -automaticDataCollectionEnabled?: boolean; -``` - -## FirebaseAppSettings.name - -custom name for the Firebase App. The default value is `"[DEFAULT]"`. - -Signature: - -```typescript -name?: string; -``` diff --git a/docs-devsite/app.firebaseoptions.md b/docs-devsite/app.firebaseoptions.md deleted file mode 100644 index 5061c901676..00000000000 --- a/docs-devsite/app.firebaseoptions.md +++ /dev/null @@ -1,112 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FirebaseOptions interface -Firebase configuration object. Contains a set of parameters required by services in order to successfully communicate with Firebase server APIs and to associate client data with your Firebase project and Firebase application. Typically this object is populated by the Firebase console at project setup. See also: [Learn about the Firebase config object](https://firebase.google.com/docs/web/setup#config-object). - -Signature: - -```typescript -export interface FirebaseOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [apiKey](./app.firebaseoptions.md#firebaseoptionsapikey) | string | An encrypted string used when calling certain APIs that don't need to access private user data (example value: AIzaSyDOCAbC123dEf456GhI789jKl012-MnO). | -| [appId](./app.firebaseoptions.md#firebaseoptionsappid) | string | Unique identifier for the app. | -| [authDomain](./app.firebaseoptions.md#firebaseoptionsauthdomain) | string | Auth domain for the project ID. | -| [databaseURL](./app.firebaseoptions.md#firebaseoptionsdatabaseurl) | string | Default Realtime Database URL. | -| [measurementId](./app.firebaseoptions.md#firebaseoptionsmeasurementid) | string | An ID automatically created when you enable Analytics in your Firebase project and register a web app. In versions 7.20.0 and higher, this parameter is optional. | -| [messagingSenderId](./app.firebaseoptions.md#firebaseoptionsmessagingsenderid) | string | Unique numerical value used to identify each sender that can send Firebase Cloud Messaging messages to client apps. | -| [projectId](./app.firebaseoptions.md#firebaseoptionsprojectid) | string | The unique identifier for the project across all of Firebase and Google Cloud. | -| [storageBucket](./app.firebaseoptions.md#firebaseoptionsstoragebucket) | string | The default Cloud Storage bucket name. | - -## FirebaseOptions.apiKey - -An encrypted string used when calling certain APIs that don't need to access private user data (example value: `AIzaSyDOCAbC123dEf456GhI789jKl012-MnO`). - -Signature: - -```typescript -apiKey?: string; -``` - -## FirebaseOptions.appId - -Unique identifier for the app. - -Signature: - -```typescript -appId?: string; -``` - -## FirebaseOptions.authDomain - -Auth domain for the project ID. - -Signature: - -```typescript -authDomain?: string; -``` - -## FirebaseOptions.databaseURL - -Default Realtime Database URL. - -Signature: - -```typescript -databaseURL?: string; -``` - -## FirebaseOptions.measurementId - -An ID automatically created when you enable Analytics in your Firebase project and register a web app. In versions 7.20.0 and higher, this parameter is optional. - -Signature: - -```typescript -measurementId?: string; -``` - -## FirebaseOptions.messagingSenderId - -Unique numerical value used to identify each sender that can send Firebase Cloud Messaging messages to client apps. - -Signature: - -```typescript -messagingSenderId?: string; -``` - -## FirebaseOptions.projectId - -The unique identifier for the project across all of Firebase and Google Cloud. - -Signature: - -```typescript -projectId?: string; -``` - -## FirebaseOptions.storageBucket - -The default Cloud Storage bucket name. - -Signature: - -```typescript -storageBucket?: string; -``` diff --git a/docs-devsite/app.md b/docs-devsite/app.md deleted file mode 100644 index babb7d7bd2b..00000000000 --- a/docs-devsite/app.md +++ /dev/null @@ -1,306 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# app package -Firebase App - -This package coordinates the communication between the different Firebase components - -## Functions - -| Function | Description | -| --- | --- | -| function(app...) | -| [deleteApp(app)](./app.md#deleteapp) | Renders this app unusable and frees the resources of all associated services. | -| function() | -| [getApps()](./app.md#getapps) | A (read-only) array of all initialized apps. | -| [initializeApp()](./app.md#initializeapp) | Creates and initializes a FirebaseApp instance. | -| function(libraryKeyOrName...) | -| [registerVersion(libraryKeyOrName, version, variant)](./app.md#registerversion) | Registers a library's name and version for platform logging purposes. | -| function(logCallback...) | -| [onLog(logCallback, options)](./app.md#onlog) | Sets log handler for all Firebase SDKs. | -| function(logLevel...) | -| [setLogLevel(logLevel)](./app.md#setloglevel) | Sets log level for all Firebase SDKs.All of the log types above the current log level are captured (i.e. if you set the log level to info, errors are logged, but debug and verbose logs are not). | -| function(name...) | -| [getApp(name)](./app.md#getapp) | Retrieves a [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance.When called with no arguments, the default app is returned. When an app name is provided, the app corresponding to that name is returned.An exception is thrown if the app being retrieved has not yet been initialized. | -| function(options...) | -| [initializeApp(options, name)](./app.md#initializeapp) | Creates and initializes a [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance.See [Add Firebase to your app](https://firebase.google.com/docs/web/setup#add_firebase_to_your_app) and [Initialize multiple projects](https://firebase.google.com/docs/web/setup#multiple-projects) for detailed documentation. | -| [initializeApp(options, config)](./app.md#initializeapp) | Creates and initializes a FirebaseApp instance. | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | A [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) holds the initialization information for a collection of services.Do not call this constructor directly. Instead, use [initializeApp()](./app.md#initializeapp) to create an app. | -| [FirebaseAppSettings](./app.firebaseappsettings.md#firebaseappsettings_interface) | Configuration options given to [initializeApp()](./app.md#initializeapp) | -| [FirebaseOptions](./app.firebaseoptions.md#firebaseoptions_interface) | Firebase configuration object. Contains a set of parameters required by services in order to successfully communicate with Firebase server APIs and to associate client data with your Firebase project and Firebase application. Typically this object is populated by the Firebase console at project setup. See also: [Learn about the Firebase config object](https://firebase.google.com/docs/web/setup#config-object). | - -## Variables - -| Variable | Description | -| --- | --- | -| [SDK\_VERSION](./app.md#sdk_version) | The current SDK version. | - -## deleteApp() - -Renders this app unusable and frees the resources of all associated services. - -Signature: - -```typescript -export declare function deleteApp(app: FirebaseApp): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | | - -Returns: - -Promise<void> - -### Example - - -```javascript -deleteApp(app) - .then(function() { - console.log("App deleted successfully"); - }) - .catch(function(error) { - console.log("Error deleting app:", error); - }); - -``` - -## getApps() - -A (read-only) array of all initialized apps. - -Signature: - -```typescript -export declare function getApps(): FirebaseApp[]; -``` -Returns: - -[FirebaseApp](./app.firebaseapp.md#firebaseapp_interface)\[\] - -## initializeApp() - -Creates and initializes a FirebaseApp instance. - -Signature: - -```typescript -export declare function initializeApp(): FirebaseApp; -``` -Returns: - -[FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) - -## registerVersion() - -Registers a library's name and version for platform logging purposes. - -Signature: - -```typescript -export declare function registerVersion(libraryKeyOrName: string, version: string, variant?: string): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| libraryKeyOrName | string | | -| version | string | Current version of that library. | -| variant | string | Bundle variant, e.g., node, rn, etc. | - -Returns: - -void - -## onLog() - -Sets log handler for all Firebase SDKs. - -Signature: - -```typescript -export declare function onLog(logCallback: LogCallback | null, options?: LogOptions): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| logCallback | LogCallback \| null | An optional custom log handler that executes user code whenever the Firebase SDK makes a logging call. | -| options | LogOptions | | - -Returns: - -void - -## setLogLevel() - -Sets log level for all Firebase SDKs. - -All of the log types above the current log level are captured (i.e. if you set the log level to `info`, errors are logged, but `debug` and `verbose` logs are not). - -Signature: - -```typescript -export declare function setLogLevel(logLevel: LogLevelString): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| logLevel | LogLevelString | | - -Returns: - -void - -## getApp() - -Retrieves a [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. - -When called with no arguments, the default app is returned. When an app name is provided, the app corresponding to that name is returned. - -An exception is thrown if the app being retrieved has not yet been initialized. - -Signature: - -```typescript -export declare function getApp(name?: string): FirebaseApp; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| name | string | Optional name of the app to return. If no name is provided, the default is "[DEFAULT]". | - -Returns: - -[FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) - -The app corresponding to the provided app name. If no app name is provided, the default app is returned. - -### Example 1 - - -```javascript -// Return the default app -const app = getApp(); - -``` - -### Example 2 - - -```javascript -// Return a named app -const otherApp = getApp("otherApp"); - -``` - -## initializeApp() - -Creates and initializes a [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. - -See [Add Firebase to your app](https://firebase.google.com/docs/web/setup#add_firebase_to_your_app) and [Initialize multiple projects](https://firebase.google.com/docs/web/setup#multiple-projects) for detailed documentation. - -Signature: - -```typescript -export declare function initializeApp(options: FirebaseOptions, name?: string): FirebaseApp; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| options | [FirebaseOptions](./app.firebaseoptions.md#firebaseoptions_interface) | Options to configure the app's services. | -| name | string | Optional name of the app to initialize. If no name is provided, the default is "[DEFAULT]". | - -Returns: - -[FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) - -The initialized app. - -### Example 1 - - -```javascript - -// Initialize default app -// Retrieve your own options values by adding a web app on -// https://console.firebase.google.com -initializeApp({ - apiKey: "AIza....", // Auth / General Use - authDomain: "YOUR_APP.firebaseapp.com", // Auth with popup/redirect - databaseURL: "https://YOUR_APP.firebaseio.com", // Realtime Database - storageBucket: "YOUR_APP.appspot.com", // Storage - messagingSenderId: "123456789" // Cloud Messaging -}); - -``` - -### Example 2 - - -```javascript - -// Initialize another app -const otherApp = initializeApp({ - databaseURL: "https://.firebaseio.com", - storageBucket: ".appspot.com" -}, "otherApp"); - -``` - -## initializeApp() - -Creates and initializes a FirebaseApp instance. - -Signature: - -```typescript -export declare function initializeApp(options: FirebaseOptions, config?: FirebaseAppSettings): FirebaseApp; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| options | [FirebaseOptions](./app.firebaseoptions.md#firebaseoptions_interface) | Options to configure the app's services. | -| config | [FirebaseAppSettings](./app.firebaseappsettings.md#firebaseappsettings_interface) | FirebaseApp Configuration | - -Returns: - -[FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) - -## SDK\_VERSION - -The current SDK version. - -Signature: - -```typescript -SDK_VERSION: string -``` diff --git a/docs-devsite/auth.actioncodeinfo.md b/docs-devsite/auth.actioncodeinfo.md deleted file mode 100644 index 980acf6d967..00000000000 --- a/docs-devsite/auth.actioncodeinfo.md +++ /dev/null @@ -1,58 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ActionCodeInfo interface -A response from [checkActionCode()](./auth.md#checkactioncode). - -Signature: - -```typescript -export interface ActionCodeInfo -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [data](./auth.actioncodeinfo.md#actioncodeinfodata) | { email?: string \| null; multiFactorInfo?: [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) \| null; previousEmail?: string \| null; } | The data associated with the action code. | -| [operation](./auth.actioncodeinfo.md#actioncodeinfooperation) | typeof [ActionCodeOperationMap](./auth.md#actioncodeoperation)\[keyof typeof [ActionCodeOperationMap](./auth.md#actioncodeoperation)\] | The type of operation that generated the action code. | - -## ActionCodeInfo.data - -The data associated with the action code. - -For the [ActionCodeOperation](./auth.md#actioncodeoperation).PASSWORD\_RESET, [ActionCodeOperation](./auth.md#actioncodeoperation).VERIFY\_EMAIL, and [ActionCodeOperation](./auth.md#actioncodeoperation).RECOVER\_EMAIL actions, this object contains an email field with the address the email was sent to. - -For the [ActionCodeOperation](./auth.md#actioncodeoperation).RECOVER\_EMAIL action, which allows a user to undo an email address change, this object also contains a `previousEmail` field with the user account's current email address. After the action completes, the user's email address will revert to the value in the `email` field from the value in `previousEmail` field. - -For the [ActionCodeOperation](./auth.md#actioncodeoperation).VERIFY\_AND\_CHANGE\_EMAIL action, which allows a user to verify the email before updating it, this object contains a `previousEmail` field with the user account's email address before updating. After the action completes, the user's email address will be updated to the value in the `email` field from the value in `previousEmail` field. - -For the [ActionCodeOperation](./auth.md#actioncodeoperation).REVERT\_SECOND\_FACTOR\_ADDITION action, which allows a user to unenroll a newly added second factor, this object contains a `multiFactorInfo` field with the information about the second factor. For phone second factor, the `multiFactorInfo` is a [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) object, which contains the phone number. - -Signature: - -```typescript -data: { - email?: string | null; - multiFactorInfo?: MultiFactorInfo | null; - previousEmail?: string | null; - }; -``` - -## ActionCodeInfo.operation - -The type of operation that generated the action code. - -Signature: - -```typescript -operation: typeof ActionCodeOperationMap[keyof typeof ActionCodeOperationMap]; -``` diff --git a/docs-devsite/auth.actioncodesettings.md b/docs-devsite/auth.actioncodesettings.md deleted file mode 100644 index a12144adaf4..00000000000 --- a/docs-devsite/auth.actioncodesettings.md +++ /dev/null @@ -1,95 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ActionCodeSettings interface -An interface that defines the required continue/state URL with optional Android and iOS bundle identifiers. - -Signature: - -```typescript -export interface ActionCodeSettings -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [android](./auth.actioncodesettings.md#actioncodesettingsandroid) | { installApp?: boolean; minimumVersion?: string; packageName: string; } | Sets the Android package name. | -| [dynamicLinkDomain](./auth.actioncodesettings.md#actioncodesettingsdynamiclinkdomain) | string | When multiple custom dynamic link domains are defined for a project, specify which one to use when the link is to be opened via a specified mobile app (for example, example.page.link). | -| [handleCodeInApp](./auth.actioncodesettings.md#actioncodesettingshandlecodeinapp) | boolean | When set to true, the action code link will be be sent as a Universal Link or Android App Link and will be opened by the app if installed. | -| [iOS](./auth.actioncodesettings.md#actioncodesettingsios) | { bundleId: string; } | Sets the iOS bundle ID. | -| [url](./auth.actioncodesettings.md#actioncodesettingsurl) | string | Sets the link continue/state URL. | - -## ActionCodeSettings.android - -Sets the Android package name. - -This will try to open the link in an android app if it is installed. If `installApp` is passed, it specifies whether to install the Android app if the device supports it and the app is not already installed. If this field is provided without a `packageName`, an error is thrown explaining that the `packageName` must be provided in conjunction with this field. If `minimumVersion` is specified, and an older version of the app is installed, the user is taken to the Play Store to upgrade the app. - -Signature: - -```typescript -android?: { - installApp?: boolean; - minimumVersion?: string; - packageName: string; - }; -``` - -## ActionCodeSettings.dynamicLinkDomain - -When multiple custom dynamic link domains are defined for a project, specify which one to use when the link is to be opened via a specified mobile app (for example, `example.page.link`). - -Signature: - -```typescript -dynamicLinkDomain?: string; -``` - -## ActionCodeSettings.handleCodeInApp - -When set to true, the action code link will be be sent as a Universal Link or Android App Link and will be opened by the app if installed. - -In the false case, the code will be sent to the web widget first and then on continue will redirect to the app if installed. - -Signature: - -```typescript -handleCodeInApp?: boolean; -``` - -## ActionCodeSettings.iOS - -Sets the iOS bundle ID. - -This will try to open the link in an iOS app if it is installed. - -App installation is not supported for iOS. - -Signature: - -```typescript -iOS?: { - bundleId: string; - }; -``` - -## ActionCodeSettings.url - -Sets the link continue/state URL. - -This has different meanings in different contexts: - When the link is handled in the web action widgets, this is the deep link in the `continueUrl` query parameter. - When the link is handled in the app directly, this is the `continueUrl` query parameter in the deep link of the Dynamic Link. - -Signature: - -```typescript -url: string; -``` diff --git a/docs-devsite/auth.actioncodeurl.md b/docs-devsite/auth.actioncodeurl.md deleted file mode 100644 index f59e20d8c15..00000000000 --- a/docs-devsite/auth.actioncodeurl.md +++ /dev/null @@ -1,121 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ActionCodeURL class -A utility class to parse email action URLs such as password reset, email verification, email link sign in, etc. - -The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `ActionCodeURL` class. - -Signature: - -```typescript -export declare class ActionCodeURL -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [apiKey](./auth.actioncodeurl.md#actioncodeurlapikey) | | string | The API key of the email action link. | -| [code](./auth.actioncodeurl.md#actioncodeurlcode) | | string | The action code of the email action link. | -| [continueUrl](./auth.actioncodeurl.md#actioncodeurlcontinueurl) | | string \| null | The continue URL of the email action link. Null if not provided. | -| [languageCode](./auth.actioncodeurl.md#actioncodeurllanguagecode) | | string \| null | The language code of the email action link. Null if not provided. | -| [operation](./auth.actioncodeurl.md#actioncodeurloperation) | | string | The action performed by the email action link. It returns from one of the types from [ActionCodeInfo](./auth.actioncodeinfo.md#actioncodeinfo_interface) | -| [tenantId](./auth.actioncodeurl.md#actioncodeurltenantid) | | string \| null | The tenant ID of the email action link. Null if the email action is from the parent project. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [parseLink(link)](./auth.actioncodeurl.md#actioncodeurlparselink) | static | Parses the email action link string and returns an [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) if the link is valid, otherwise returns null. | - -## ActionCodeURL.apiKey - -The API key of the email action link. - -Signature: - -```typescript -readonly apiKey: string; -``` - -## ActionCodeURL.code - -The action code of the email action link. - -Signature: - -```typescript -readonly code: string; -``` - -## ActionCodeURL.continueUrl - -The continue URL of the email action link. Null if not provided. - -Signature: - -```typescript -readonly continueUrl: string | null; -``` - -## ActionCodeURL.languageCode - -The language code of the email action link. Null if not provided. - -Signature: - -```typescript -readonly languageCode: string | null; -``` - -## ActionCodeURL.operation - -The action performed by the email action link. It returns from one of the types from [ActionCodeInfo](./auth.actioncodeinfo.md#actioncodeinfo_interface) - -Signature: - -```typescript -readonly operation: string; -``` - -## ActionCodeURL.tenantId - -The tenant ID of the email action link. Null if the email action is from the parent project. - -Signature: - -```typescript -readonly tenantId: string | null; -``` - -## ActionCodeURL.parseLink() - -Parses the email action link string and returns an [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) if the link is valid, otherwise returns null. - -Signature: - -```typescript -static parseLink(link: string): ActionCodeURL | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| link | string | The email action link string. | - -Returns: - -[ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) \| null - -The [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) object, or null if the link is invalid. - diff --git a/docs-devsite/auth.additionaluserinfo.md b/docs-devsite/auth.additionaluserinfo.md deleted file mode 100644 index ec6ca5740ac..00000000000 --- a/docs-devsite/auth.additionaluserinfo.md +++ /dev/null @@ -1,68 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AdditionalUserInfo interface -A structure containing additional user information from a federated identity provider. - -Signature: - -```typescript -export interface AdditionalUserInfo -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [isNewUser](./auth.additionaluserinfo.md#additionaluserinfoisnewuser) | boolean | Whether the user is new (created via sign-up) or existing (authenticated using sign-in). | -| [profile](./auth.additionaluserinfo.md#additionaluserinfoprofile) | Record<string, unknown> \| null | Map containing IDP-specific user data. | -| [providerId](./auth.additionaluserinfo.md#additionaluserinfoproviderid) | string \| null | Identifier for the provider used to authenticate this user. | -| [username](./auth.additionaluserinfo.md#additionaluserinfousername) | string \| null | The username if the provider is GitHub or Twitter. | - -## AdditionalUserInfo.isNewUser - -Whether the user is new (created via sign-up) or existing (authenticated using sign-in). - -Signature: - -```typescript -readonly isNewUser: boolean; -``` - -## AdditionalUserInfo.profile - -Map containing IDP-specific user data. - -Signature: - -```typescript -readonly profile: Record | null; -``` - -## AdditionalUserInfo.providerId - -Identifier for the provider used to authenticate this user. - -Signature: - -```typescript -readonly providerId: string | null; -``` - -## AdditionalUserInfo.username - -The username if the provider is GitHub or Twitter. - -Signature: - -```typescript -readonly username?: string | null; -``` diff --git a/docs-devsite/auth.applicationverifier.md b/docs-devsite/auth.applicationverifier.md deleted file mode 100644 index 08e81aa3362..00000000000 --- a/docs-devsite/auth.applicationverifier.md +++ /dev/null @@ -1,59 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ApplicationVerifier interface -A verifier for domain verification and abuse prevention. - -Currently, the only implementation is [RecaptchaVerifier](./auth.recaptchaverifier.md#recaptchaverifier_class). - -Signature: - -```typescript -export interface ApplicationVerifier -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [type](./auth.applicationverifier.md#applicationverifiertype) | string | Identifies the type of application verifier (e.g. "recaptcha"). | - -## Methods - -| Method | Description | -| --- | --- | -| [verify()](./auth.applicationverifier.md#applicationverifierverify) | Executes the verification process. | - -## ApplicationVerifier.type - -Identifies the type of application verifier (e.g. "recaptcha"). - -Signature: - -```typescript -readonly type: string; -``` - -## ApplicationVerifier.verify() - -Executes the verification process. - -Signature: - -```typescript -verify(): Promise; -``` -Returns: - -Promise<string> - -A Promise for a token that can be used to assert the validity of a request. - diff --git a/docs-devsite/auth.auth.md b/docs-devsite/auth.auth.md deleted file mode 100644 index 9bd59ba6c56..00000000000 --- a/docs-devsite/auth.auth.md +++ /dev/null @@ -1,299 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Auth interface -Interface representing Firebase Auth service. - -See [Firebase Authentication](https://firebase.google.com/docs/auth/) for a full guide on how to use the Firebase Auth service. - -Signature: - -```typescript -export interface Auth -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [app](./auth.auth.md#authapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with the Auth service instance. | -| [config](./auth.auth.md#authconfig) | [Config](./auth.config.md#config_interface) | The [Config](./auth.config.md#config_interface) used to initialize this instance. | -| [currentUser](./auth.auth.md#authcurrentuser) | [User](./auth.user.md#user_interface) \| null | The currently signed-in user (or null). | -| [emulatorConfig](./auth.auth.md#authemulatorconfig) | [EmulatorConfig](./auth.emulatorconfig.md#emulatorconfig_interface) \| null | The current emulator configuration (or null). | -| [languageCode](./auth.auth.md#authlanguagecode) | string \| null | The [Auth](./auth.auth.md#auth_interface) instance's language code. | -| [name](./auth.auth.md#authname) | string | The name of the app associated with the Auth service instance. | -| [settings](./auth.auth.md#authsettings) | [AuthSettings](./auth.authsettings.md#authsettings_interface) | The [Auth](./auth.auth.md#auth_interface) instance's settings. | -| [tenantId](./auth.auth.md#authtenantid) | string \| null | The [Auth](./auth.auth.md#auth_interface) instance's tenant ID. | - -## Methods - -| Method | Description | -| --- | --- | -| [beforeAuthStateChanged(callback, onAbort)](./auth.auth.md#authbeforeauthstatechanged) | Adds a blocking callback that runs before an auth state change sets a new user. | -| [onAuthStateChanged(nextOrObserver, error, completed)](./auth.auth.md#authonauthstatechanged) | Adds an observer for changes to the user's sign-in state. | -| [onIdTokenChanged(nextOrObserver, error, completed)](./auth.auth.md#authonidtokenchanged) | Adds an observer for changes to the signed-in user's ID token. | -| [setPersistence(persistence)](./auth.auth.md#authsetpersistence) | Changes the type of persistence on the Auth instance. | -| [signOut()](./auth.auth.md#authsignout) | Signs out the current user. | -| [updateCurrentUser(user)](./auth.auth.md#authupdatecurrentuser) | Asynchronously sets the provided user as [Auth.currentUser](./auth.auth.md#authcurrentuser) on the [Auth](./auth.auth.md#auth_interface) instance. | -| [useDeviceLanguage()](./auth.auth.md#authusedevicelanguage) | Sets the current language to the default device/browser preference. | - -## Auth.app - -The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with the `Auth` service instance. - -Signature: - -```typescript -readonly app: FirebaseApp; -``` - -## Auth.config - -The [Config](./auth.config.md#config_interface) used to initialize this instance. - -Signature: - -```typescript -readonly config: Config; -``` - -## Auth.currentUser - -The currently signed-in user (or null). - -Signature: - -```typescript -readonly currentUser: User | null; -``` - -## Auth.emulatorConfig - -The current emulator configuration (or null). - -Signature: - -```typescript -readonly emulatorConfig: EmulatorConfig | null; -``` - -## Auth.languageCode - -The [Auth](./auth.auth.md#auth_interface) instance's language code. - -This is a readable/writable property. When set to null, the default Firebase Console language setting is applied. The language code will propagate to email action templates (password reset, email verification and email change revocation), SMS templates for phone authentication, reCAPTCHA verifier and OAuth popup/redirect operations provided the specified providers support localization with the language code specified. - -Signature: - -```typescript -languageCode: string | null; -``` - -## Auth.name - -The name of the app associated with the `Auth` service instance. - -Signature: - -```typescript -readonly name: string; -``` - -## Auth.settings - -The [Auth](./auth.auth.md#auth_interface) instance's settings. - -This is used to edit/read configuration related options such as app verification mode for phone authentication. - -Signature: - -```typescript -readonly settings: AuthSettings; -``` - -## Auth.tenantId - -The [Auth](./auth.auth.md#auth_interface) instance's tenant ID. - -This is a readable/writable property. When you set the tenant ID of an [Auth](./auth.auth.md#auth_interface) instance, all future sign-in/sign-up operations will pass this tenant ID and sign in or sign up users to the specified tenant project. When set to null, users are signed in to the parent project. - -Signature: - -```typescript -tenantId: string | null; -``` - -### Example - - -```javascript -// Set the tenant ID on Auth instance. -auth.tenantId = 'TENANT_PROJECT_ID'; - -// All future sign-in request now include tenant ID. -const result = await signInWithEmailAndPassword(auth, email, password); -// result.user.tenantId should be 'TENANT_PROJECT_ID'. - -``` - -## Auth.beforeAuthStateChanged() - -Adds a blocking callback that runs before an auth state change sets a new user. - -Signature: - -```typescript -beforeAuthStateChanged(callback: (user: User | null) => void | Promise, onAbort?: () => void): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| callback | (user: [User](./auth.user.md#user_interface) \| null) => void \| Promise<void> | callback triggered before new user value is set. If this throws, it blocks the user from being set. | -| onAbort | () => void | callback triggered if a later beforeAuthStateChanged() callback throws, allowing you to undo any side effects. | - -Returns: - -[Unsubscribe](./util.md#unsubscribe) - -## Auth.onAuthStateChanged() - -Adds an observer for changes to the user's sign-in state. - -To keep the old behavior, see [Auth.onIdTokenChanged()](./auth.auth.md#authonidtokenchanged). - -Signature: - -```typescript -onAuthStateChanged(nextOrObserver: NextOrObserver, error?: ErrorFn, completed?: CompleteFn): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| nextOrObserver | [NextOrObserver](./auth.md#nextorobserver)<[User](./auth.user.md#user_interface) \| null> | callback triggered on change. | -| error | [ErrorFn](./util.md#errorfn) | Deprecated. This callback is never triggered. Errors on signing in/out can be caught in promises returned from sign-in/sign-out functions. | -| completed | [CompleteFn](./util.md#completefn) | Deprecated. This callback is never triggered. | - -Returns: - -[Unsubscribe](./util.md#unsubscribe) - -## Auth.onIdTokenChanged() - -Adds an observer for changes to the signed-in user's ID token. - -This includes sign-in, sign-out, and token refresh events. - -Signature: - -```typescript -onIdTokenChanged(nextOrObserver: NextOrObserver, error?: ErrorFn, completed?: CompleteFn): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| nextOrObserver | [NextOrObserver](./auth.md#nextorobserver)<[User](./auth.user.md#user_interface) \| null> | callback triggered on change. | -| error | [ErrorFn](./util.md#errorfn) | Deprecated. This callback is never triggered. Errors on signing in/out can be caught in promises returned from sign-in/sign-out functions. | -| completed | [CompleteFn](./util.md#completefn) | Deprecated. This callback is never triggered. | - -Returns: - -[Unsubscribe](./util.md#unsubscribe) - -## Auth.setPersistence() - -Changes the type of persistence on the `Auth` instance. - -This will affect the currently saved Auth session and applies this type of persistence for future sign-in requests, including sign-in with redirect requests. - -This makes it easy for a user signing in to specify whether their session should be remembered or not. It also makes it easier to never persist the Auth state for applications that are shared by other users or have sensitive data. - -Signature: - -```typescript -setPersistence(persistence: Persistence): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| persistence | [Persistence](./auth.persistence.md#persistence_interface) | The [Persistence](./auth.persistence.md#persistence_interface) to use. | - -Returns: - -Promise<void> - -### Example - - -```javascript -auth.setPersistence(browserSessionPersistence); - -``` - -## Auth.signOut() - -Signs out the current user. - -Signature: - -```typescript -signOut(): Promise; -``` -Returns: - -Promise<void> - -## Auth.updateCurrentUser() - -Asynchronously sets the provided user as [Auth.currentUser](./auth.auth.md#authcurrentuser) on the [Auth](./auth.auth.md#auth_interface) instance. - -A new instance copy of the user provided will be made and set as currentUser. - -This will trigger [Auth.onAuthStateChanged()](./auth.auth.md#authonauthstatechanged) and [Auth.onIdTokenChanged()](./auth.auth.md#authonidtokenchanged) listeners like other sign in methods. - -The operation fails with an error if the user to be updated belongs to a different Firebase project. - -Signature: - -```typescript -updateCurrentUser(user: User | null): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) \| null | The new [User](./auth.user.md#user_interface). | - -Returns: - -Promise<void> - -## Auth.useDeviceLanguage() - -Sets the current language to the default device/browser preference. - -Signature: - -```typescript -useDeviceLanguage(): void; -``` -Returns: - -void - diff --git a/docs-devsite/auth.authcredential.md b/docs-devsite/auth.authcredential.md deleted file mode 100644 index fdc6fe392c4..00000000000 --- a/docs-devsite/auth.authcredential.md +++ /dev/null @@ -1,76 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AuthCredential class -Interface that represents the credentials returned by an [AuthProvider](./auth.authprovider.md#authprovider_interface). - -Implementations specify the details about each auth provider's credential requirements. - -The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `AuthCredential` class. - -Signature: - -```typescript -export declare class AuthCredential -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [providerId](./auth.authcredential.md#authcredentialproviderid) | | string | The authentication provider ID for the credential. | -| [signInMethod](./auth.authcredential.md#authcredentialsigninmethod) | | string | The authentication sign in method for the credential. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [toJSON()](./auth.authcredential.md#authcredentialtojson) | | Returns a JSON-serializable representation of this object. | - -## AuthCredential.providerId - -The authentication provider ID for the credential. - -For example, 'facebook.com', or 'google.com'. - -Signature: - -```typescript -readonly providerId: string; -``` - -## AuthCredential.signInMethod - -The authentication sign in method for the credential. - -For example, [SignInMethod](./auth.md#signinmethod).EMAIL\_PASSWORD, or [SignInMethod](./auth.md#signinmethod).EMAIL\_LINK. This corresponds to the sign-in method identifier as returned in [fetchSignInMethodsForEmail()](./auth.md#fetchsigninmethodsforemail). - -Signature: - -```typescript -readonly signInMethod: string; -``` - -## AuthCredential.toJSON() - -Returns a JSON-serializable representation of this object. - -Signature: - -```typescript -toJSON(): object; -``` -Returns: - -object - -a JSON-serializable representation of this object. - diff --git a/docs-devsite/auth.autherror.md b/docs-devsite/auth.autherror.md deleted file mode 100644 index f91b835b5ed..00000000000 --- a/docs-devsite/auth.autherror.md +++ /dev/null @@ -1,41 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AuthError interface -Interface for an `Auth` error. - -Signature: - -```typescript -export interface AuthError extends FirebaseError -``` -Extends: [FirebaseError](./util.firebaseerror.md#firebaseerror_class) - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [customData](./auth.autherror.md#autherrorcustomdata) | { readonly appName: string; readonly email?: string; readonly phoneNumber?: string; readonly tenantId?: string; } | Details about the Firebase Auth error. | - -## AuthError.customData - -Details about the Firebase Auth error. - -Signature: - -```typescript -readonly customData: { - readonly appName: string; - readonly email?: string; - readonly phoneNumber?: string; - readonly tenantId?: string; - }; -``` diff --git a/docs-devsite/auth.autherrormap.md b/docs-devsite/auth.autherrormap.md deleted file mode 100644 index e0316a8ed59..00000000000 --- a/docs-devsite/auth.autherrormap.md +++ /dev/null @@ -1,27 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AuthErrorMap interface -A mapping of error codes to error messages. - -While error messages are useful for debugging (providing verbose textual context around what went wrong), these strings take up a lot of space in the compiled code. When deploying code in production, using [prodErrorMap](./auth.md#proderrormap) will save you roughly 10k compressed/gzipped over [debugErrorMap](./auth.md#debugerrormap). You can select the error map during initialization: - -```javascript -initializeAuth(app, {errorMap: debugErrorMap}) - -``` -When initializing Auth, [prodErrorMap](./auth.md#proderrormap) is default. - -Signature: - -```typescript -export interface AuthErrorMap -``` diff --git a/docs-devsite/auth.authprovider.md b/docs-devsite/auth.authprovider.md deleted file mode 100644 index a9871dad0a8..00000000000 --- a/docs-devsite/auth.authprovider.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AuthProvider interface -Interface that represents an auth provider, used to facilitate creating [AuthCredential](./auth.authcredential.md#authcredential_class). - -Signature: - -```typescript -export interface AuthProvider -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [providerId](./auth.authprovider.md#authproviderproviderid) | string | Provider for which credentials can be constructed. | - -## AuthProvider.providerId - -Provider for which credentials can be constructed. - -Signature: - -```typescript -readonly providerId: string; -``` diff --git a/docs-devsite/auth.authsettings.md b/docs-devsite/auth.authsettings.md deleted file mode 100644 index c54fac47da4..00000000000 --- a/docs-devsite/auth.authsettings.md +++ /dev/null @@ -1,41 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AuthSettings interface -Interface representing an [Auth](./auth.auth.md#auth_interface) instance's settings. - -Currently used for enabling/disabling app verification for phone Auth testing. - -Signature: - -```typescript -export interface AuthSettings -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [appVerificationDisabledForTesting](./auth.authsettings.md#authsettingsappverificationdisabledfortesting) | boolean | When set, this property disables app verification for the purpose of testing phone authentication. For this property to take effect, it needs to be set before rendering a reCAPTCHA app verifier. When this is disabled, a mock reCAPTCHA is rendered instead. This is useful for manual testing during development or for automated integration tests.In order to use this feature, you will need to [whitelist your phone number](https://firebase.google.com/docs/auth/web/phone-auth#test-with-whitelisted-phone-numbers) via the Firebase Console.The default value is false (app verification is enabled). | - -## AuthSettings.appVerificationDisabledForTesting - -When set, this property disables app verification for the purpose of testing phone authentication. For this property to take effect, it needs to be set before rendering a reCAPTCHA app verifier. When this is disabled, a mock reCAPTCHA is rendered instead. This is useful for manual testing during development or for automated integration tests. - -In order to use this feature, you will need to [whitelist your phone number](https://firebase.google.com/docs/auth/web/phone-auth#test-with-whitelisted-phone-numbers) via the Firebase Console. - -The default value is false (app verification is enabled). - -Signature: - -```typescript -appVerificationDisabledForTesting: boolean; -``` diff --git a/docs-devsite/auth.config.md b/docs-devsite/auth.config.md deleted file mode 100644 index c22a3930f87..00000000000 --- a/docs-devsite/auth.config.md +++ /dev/null @@ -1,90 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Config interface -Interface representing the `Auth` config. - -Signature: - -```typescript -export interface Config -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [apiHost](./auth.config.md#configapihost) | string | The host at which the Firebase Auth backend is running. | -| [apiKey](./auth.config.md#configapikey) | string | The API Key used to communicate with the Firebase Auth backend. | -| [apiScheme](./auth.config.md#configapischeme) | string | The scheme used to communicate with the Firebase Auth backend. | -| [authDomain](./auth.config.md#configauthdomain) | string | The domain at which the web widgets are hosted (provided via Firebase Config). | -| [sdkClientVersion](./auth.config.md#configsdkclientversion) | string | The SDK Client Version. | -| [tokenApiHost](./auth.config.md#configtokenapihost) | string | The host at which the Secure Token API is running. | - -## Config.apiHost - -The host at which the Firebase Auth backend is running. - -Signature: - -```typescript -apiHost: string; -``` - -## Config.apiKey - -The API Key used to communicate with the Firebase Auth backend. - -Signature: - -```typescript -apiKey: string; -``` - -## Config.apiScheme - -The scheme used to communicate with the Firebase Auth backend. - -Signature: - -```typescript -apiScheme: string; -``` - -## Config.authDomain - -The domain at which the web widgets are hosted (provided via Firebase Config). - -Signature: - -```typescript -authDomain?: string; -``` - -## Config.sdkClientVersion - -The SDK Client Version. - -Signature: - -```typescript -sdkClientVersion: string; -``` - -## Config.tokenApiHost - -The host at which the Secure Token API is running. - -Signature: - -```typescript -tokenApiHost: string; -``` diff --git a/docs-devsite/auth.confirmationresult.md b/docs-devsite/auth.confirmationresult.md deleted file mode 100644 index 5d6a209b12d..00000000000 --- a/docs-devsite/auth.confirmationresult.md +++ /dev/null @@ -1,74 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ConfirmationResult interface -A result from a phone number sign-in, link, or reauthenticate call. - -Signature: - -```typescript -export interface ConfirmationResult -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [verificationId](./auth.confirmationresult.md#confirmationresultverificationid) | string | The phone number authentication operation's verification ID. | - -## Methods - -| Method | Description | -| --- | --- | -| [confirm(verificationCode)](./auth.confirmationresult.md#confirmationresultconfirm) | Finishes a phone number sign-in, link, or reauthentication. | - -## ConfirmationResult.verificationId - -The phone number authentication operation's verification ID. - -This can be used along with the verification code to initialize a [PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class). - -Signature: - -```typescript -readonly verificationId: string; -``` - -## ConfirmationResult.confirm() - -Finishes a phone number sign-in, link, or reauthentication. - -Signature: - -```typescript -confirm(verificationCode: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| verificationCode | string | The code that was sent to the user's mobile device. | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -### Example - - -```javascript -const confirmationResult = await signInWithPhoneNumber(auth, phoneNumber, applicationVerifier); -// Obtain verificationCode from the user. -const userCredential = await confirmationResult.confirm(verificationCode); - -``` - diff --git a/docs-devsite/auth.dependencies.md b/docs-devsite/auth.dependencies.md deleted file mode 100644 index 9112f016fa1..00000000000 --- a/docs-devsite/auth.dependencies.md +++ /dev/null @@ -1,63 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Dependencies interface -The dependencies that can be used to initialize an [Auth](./auth.auth.md#auth_interface) instance. - -The modular SDK enables tree shaking by allowing explicit declarations of dependencies. For example, a web app does not need to include code that enables Cordova redirect sign in. That functionality is therefore split into [browserPopupRedirectResolver](./auth.md#browserpopupredirectresolver) and [cordovaPopupRedirectResolver](./auth.md#cordovapopupredirectresolver). The dependencies object is how Auth is configured to reduce bundle sizes. - -There are two ways to initialize an [Auth](./auth.auth.md#auth_interface) instance: [getAuth()](./auth.md#getauth) and [initializeAuth()](./auth.md#initializeauth). `getAuth` initializes everything using platform-specific configurations, while `initializeAuth` takes a `Dependencies` object directly, giving you more control over what is used. - -Signature: - -```typescript -export interface Dependencies -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [errorMap](./auth.dependencies.md#dependencieserrormap) | [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) | Which [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) to use. | -| [persistence](./auth.dependencies.md#dependenciespersistence) | [Persistence](./auth.persistence.md#persistence_interface) \| [Persistence](./auth.persistence.md#persistence_interface)\[\] | Which [Persistence](./auth.persistence.md#persistence_interface) to use. If this is an array, the first Persistence that the device supports is used. The SDK searches for an existing account in order and, if one is found in a secondary Persistence, the account is moved to the primary Persistence.If no persistence is provided, the SDK falls back on [inMemoryPersistence](./auth.md#inmemorypersistence). | -| [popupRedirectResolver](./auth.dependencies.md#dependenciespopupredirectresolver) | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | The [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) to use. This value depends on the platform. Options are [browserPopupRedirectResolver](./auth.md#browserpopupredirectresolver) and [cordovaPopupRedirectResolver](./auth.md#cordovapopupredirectresolver). This field is optional if neither [signInWithPopup()](./auth.md#signinwithpopup) or [signInWithRedirect()](./auth.md#signinwithredirect) are being used. | - -## Dependencies.errorMap - -Which [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) to use. - -Signature: - -```typescript -errorMap?: AuthErrorMap; -``` - -## Dependencies.persistence - -Which [Persistence](./auth.persistence.md#persistence_interface) to use. If this is an array, the first `Persistence` that the device supports is used. The SDK searches for an existing account in order and, if one is found in a secondary `Persistence`, the account is moved to the primary `Persistence`. - -If no persistence is provided, the SDK falls back on [inMemoryPersistence](./auth.md#inmemorypersistence). - -Signature: - -```typescript -persistence?: Persistence | Persistence[]; -``` - -## Dependencies.popupRedirectResolver - -The [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) to use. This value depends on the platform. Options are [browserPopupRedirectResolver](./auth.md#browserpopupredirectresolver) and [cordovaPopupRedirectResolver](./auth.md#cordovapopupredirectresolver). This field is optional if neither [signInWithPopup()](./auth.md#signinwithpopup) or [signInWithRedirect()](./auth.md#signinwithredirect) are being used. - -Signature: - -```typescript -popupRedirectResolver?: PopupRedirectResolver; -``` diff --git a/docs-devsite/auth.emailauthcredential.md b/docs-devsite/auth.emailauthcredential.md deleted file mode 100644 index 5d322574b02..00000000000 --- a/docs-devsite/auth.emailauthcredential.md +++ /dev/null @@ -1,69 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# EmailAuthCredential class -Interface that represents the credentials returned by [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) for [ProviderId](./auth.md#providerid).PASSWORD - -Covers both [SignInMethod](./auth.md#signinmethod).EMAIL\_PASSWORD and [SignInMethod](./auth.md#signinmethod).EMAIL\_LINK. - -The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `EmailAuthCredential` class. - -Signature: - -```typescript -export declare class EmailAuthCredential extends AuthCredential -``` -Extends: [AuthCredential](./auth.authcredential.md#authcredential_class) - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [fromJSON(json)](./auth.emailauthcredential.md#emailauthcredentialfromjson) | static | Static method to deserialize a JSON representation of an object into an [AuthCredential](./auth.authcredential.md#authcredential_class). | -| [toJSON()](./auth.emailauthcredential.md#emailauthcredentialtojson) | | Returns a JSON-serializable representation of this object. | - -## EmailAuthCredential.fromJSON() - -Static method to deserialize a JSON representation of an object into an [AuthCredential](./auth.authcredential.md#authcredential_class). - -Signature: - -```typescript -static fromJSON(json: object | string): EmailAuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| json | object \| string | Either object or the stringified representation of the object. When string is provided, JSON.parse would be called first. | - -Returns: - -[EmailAuthCredential](./auth.emailauthcredential.md#emailauthcredential_class) \| null - -If the JSON input does not represent an [AuthCredential](./auth.authcredential.md#authcredential_class), null is returned. - -## EmailAuthCredential.toJSON() - -Returns a JSON-serializable representation of this object. - -Signature: - -```typescript -toJSON(): object; -``` -Returns: - -object - -a JSON-serializable representation of this object. - diff --git a/docs-devsite/auth.emailauthprovider.md b/docs-devsite/auth.emailauthprovider.md deleted file mode 100644 index c1834b1b8c4..00000000000 --- a/docs-devsite/auth.emailauthprovider.md +++ /dev/null @@ -1,159 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# EmailAuthProvider class -Provider for generating [EmailAuthCredential](./auth.emailauthcredential.md#emailauthcredential_class). - -Signature: - -```typescript -export declare class EmailAuthProvider implements AuthProvider -``` -Implements: [AuthProvider](./auth.authprovider.md#authprovider_interface) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [EMAIL\_LINK\_SIGN\_IN\_METHOD](./auth.emailauthprovider.md#emailauthprovideremail_link_sign_in_method) | static | 'emailLink' | Always set to [SignInMethod](./auth.md#signinmethod).EMAIL\_LINK. | -| [EMAIL\_PASSWORD\_SIGN\_IN\_METHOD](./auth.emailauthprovider.md#emailauthprovideremail_password_sign_in_method) | static | 'password' | Always set to [SignInMethod](./auth.md#signinmethod).EMAIL\_PASSWORD. | -| [PROVIDER\_ID](./auth.emailauthprovider.md#emailauthproviderprovider_id) | static | 'password' | Always set to [ProviderId](./auth.md#providerid).PASSWORD, even for email link. | -| [providerId](./auth.emailauthprovider.md#emailauthproviderproviderid) | | "password" | Always set to [ProviderId](./auth.md#providerid).PASSWORD, even for email link. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [credential(email, password)](./auth.emailauthprovider.md#emailauthprovidercredential) | static | Initialize an [AuthCredential](./auth.authcredential.md#authcredential_class) using an email and password. | -| [credentialWithLink(email, emailLink)](./auth.emailauthprovider.md#emailauthprovidercredentialwithlink) | static | Initialize an [AuthCredential](./auth.authcredential.md#authcredential_class) using an email and an email link after a sign in with email link operation. | - -## EmailAuthProvider.EMAIL\_LINK\_SIGN\_IN\_METHOD - -Always set to [SignInMethod](./auth.md#signinmethod).EMAIL\_LINK. - -Signature: - -```typescript -static readonly EMAIL_LINK_SIGN_IN_METHOD: 'emailLink'; -``` - -## EmailAuthProvider.EMAIL\_PASSWORD\_SIGN\_IN\_METHOD - -Always set to [SignInMethod](./auth.md#signinmethod).EMAIL\_PASSWORD. - -Signature: - -```typescript -static readonly EMAIL_PASSWORD_SIGN_IN_METHOD: 'password'; -``` - -## EmailAuthProvider.PROVIDER\_ID - -Always set to [ProviderId](./auth.md#providerid).PASSWORD, even for email link. - -Signature: - -```typescript -static readonly PROVIDER_ID: 'password'; -``` - -## EmailAuthProvider.providerId - -Always set to [ProviderId](./auth.md#providerid).PASSWORD, even for email link. - -Signature: - -```typescript -readonly providerId: "password"; -``` - -## EmailAuthProvider.credential() - -Initialize an [AuthCredential](./auth.authcredential.md#authcredential_class) using an email and password. - -Signature: - -```typescript -static credential(email: string, password: string): EmailAuthCredential; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| email | string | Email address. | -| password | string | User account password. | - -Returns: - -[EmailAuthCredential](./auth.emailauthcredential.md#emailauthcredential_class) - -The auth provider credential. - -### Example 1 - - -```javascript -const authCredential = EmailAuthProvider.credential(email, password); -const userCredential = await signInWithCredential(auth, authCredential); - -``` - -### Example 2 - - -```javascript -const userCredential = await signInWithEmailAndPassword(auth, email, password); - -``` - -## EmailAuthProvider.credentialWithLink() - -Initialize an [AuthCredential](./auth.authcredential.md#authcredential_class) using an email and an email link after a sign in with email link operation. - -Signature: - -```typescript -static credentialWithLink(email: string, emailLink: string): EmailAuthCredential; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| email | string | Email address. | -| emailLink | string | Sign-in email link. | - -Returns: - -[EmailAuthCredential](./auth.emailauthcredential.md#emailauthcredential_class) - -- The auth provider credential. - -### Example 1 - - -```javascript -const authCredential = EmailAuthProvider.credentialWithLink(auth, email, emailLink); -const userCredential = await signInWithCredential(auth, authCredential); - -``` - -### Example 2 - - -```javascript -await sendSignInLinkToEmail(auth, email); -// Obtain emailLink from user. -const userCredential = await signInWithEmailLink(auth, email, emailLink); - -``` - diff --git a/docs-devsite/auth.emulatorconfig.md b/docs-devsite/auth.emulatorconfig.md deleted file mode 100644 index 23f052c8dc4..00000000000 --- a/docs-devsite/auth.emulatorconfig.md +++ /dev/null @@ -1,70 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# EmulatorConfig interface -Configuration of Firebase Authentication Emulator. - -Signature: - -```typescript -export interface EmulatorConfig -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [host](./auth.emulatorconfig.md#emulatorconfighost) | string | The hostname of the emulator, which may be a domain ("localhost"), IPv4 address ("127.0.0.1") or quoted IPv6 address ("\[::1\]"). | -| [options](./auth.emulatorconfig.md#emulatorconfigoptions) | { readonly disableWarnings: boolean; } | The emulator-specific options. | -| [port](./auth.emulatorconfig.md#emulatorconfigport) | number \| null | The port of the emulator, or null if port isn't specified (i.e. protocol default). | -| [protocol](./auth.emulatorconfig.md#emulatorconfigprotocol) | string | The protocol used to communicate with the emulator ("http"/"https"). | - -## EmulatorConfig.host - -The hostname of the emulator, which may be a domain ("localhost"), IPv4 address ("127.0.0.1") or quoted IPv6 address ("\[::1\]"). - -Signature: - -```typescript -readonly host: string; -``` - -## EmulatorConfig.options - -The emulator-specific options. - -Signature: - -```typescript -readonly options: { - readonly disableWarnings: boolean; - }; -``` - -## EmulatorConfig.port - -The port of the emulator, or null if port isn't specified (i.e. protocol default). - -Signature: - -```typescript -readonly port: number | null; -``` - -## EmulatorConfig.protocol - -The protocol used to communicate with the emulator ("http"/"https"). - -Signature: - -```typescript -readonly protocol: string; -``` diff --git a/docs-devsite/auth.facebookauthprovider.md b/docs-devsite/auth.facebookauthprovider.md deleted file mode 100644 index 71ac4eea79c..00000000000 --- a/docs-devsite/auth.facebookauthprovider.md +++ /dev/null @@ -1,182 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FacebookAuthProvider class -Provider for generating an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).FACEBOOK. - -Signature: - -```typescript -export declare class FacebookAuthProvider extends BaseOAuthProvider -``` -Extends: BaseOAuthProvider - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)()](./auth.facebookauthprovider.md#facebookauthproviderconstructor) | | Constructs a new instance of the FacebookAuthProvider class | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [FACEBOOK\_SIGN\_IN\_METHOD](./auth.facebookauthprovider.md#facebookauthproviderfacebook_sign_in_method) | static | 'facebook.com' | Always set to [SignInMethod](./auth.md#signinmethod).FACEBOOK. | -| [PROVIDER\_ID](./auth.facebookauthprovider.md#facebookauthproviderprovider_id) | static | 'facebook.com' | Always set to [ProviderId](./auth.md#providerid).FACEBOOK. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [credential(accessToken)](./auth.facebookauthprovider.md#facebookauthprovidercredential) | static | Creates a credential for Facebook. | -| [credentialFromError(error)](./auth.facebookauthprovider.md#facebookauthprovidercredentialfromerror) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. | -| [credentialFromResult(userCredential)](./auth.facebookauthprovider.md#facebookauthprovidercredentialfromresult) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). | - -## FacebookAuthProvider.(constructor) - -Constructs a new instance of the `FacebookAuthProvider` class - -Signature: - -```typescript -constructor(); -``` - -## FacebookAuthProvider.FACEBOOK\_SIGN\_IN\_METHOD - -Always set to [SignInMethod](./auth.md#signinmethod).FACEBOOK. - -Signature: - -```typescript -static readonly FACEBOOK_SIGN_IN_METHOD: 'facebook.com'; -``` - -## FacebookAuthProvider.PROVIDER\_ID - -Always set to [ProviderId](./auth.md#providerid).FACEBOOK. - -Signature: - -```typescript -static readonly PROVIDER_ID: 'facebook.com'; -``` - -## FacebookAuthProvider.credential() - -Creates a credential for Facebook. - -Signature: - -```typescript -static credential(accessToken: string): OAuthCredential; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| accessToken | string | Facebook access token. | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) - -### Example - - -```javascript -// `event` from the Facebook auth.authResponseChange callback. -const credential = FacebookAuthProvider.credential(event.authResponse.accessToken); -const result = await signInWithCredential(credential); - -``` - -## FacebookAuthProvider.credentialFromError() - -Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. - -Signature: - -```typescript -static credentialFromError(error: FirebaseError): OAuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null - -## FacebookAuthProvider.credentialFromResult() - -Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). - -Signature: - -```typescript -static credentialFromResult(userCredential: UserCredential): OAuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null - -### Example 1 - - -```javascript -// Sign in using a redirect. -const provider = new FacebookAuthProvider(); -// Start a sign in process for an unauthenticated user. -provider.addScope('user_birthday'); -await signInWithRedirect(auth, provider); -// This will trigger a full page redirect away from your app - -// After returning from the redirect when your app initializes you can obtain the result -const result = await getRedirectResult(auth); -if (result) { - // This is the signed-in user - const user = result.user; - // This gives you a Facebook Access Token. - const credential = FacebookAuthProvider.credentialFromResult(result); - const token = credential.accessToken; -} - -``` - -### Example 2 - - -```javascript -// Sign in using a popup. -const provider = new FacebookAuthProvider(); -provider.addScope('user_birthday'); -const result = await signInWithPopup(auth, provider); - -// The signed-in user info. -const user = result.user; -// This gives you a Facebook Access Token. -const credential = FacebookAuthProvider.credentialFromResult(result); -const token = credential.accessToken; - -``` - diff --git a/docs-devsite/auth.githubauthprovider.md b/docs-devsite/auth.githubauthprovider.md deleted file mode 100644 index d2e04bc8125..00000000000 --- a/docs-devsite/auth.githubauthprovider.md +++ /dev/null @@ -1,174 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# GithubAuthProvider class -Provider for generating an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).GITHUB. - -GitHub requires an OAuth 2.0 redirect, so you can either handle the redirect directly, or use the [signInWithPopup()](./auth.md#signinwithpopup) handler: - -Signature: - -```typescript -export declare class GithubAuthProvider extends BaseOAuthProvider -``` -Extends: BaseOAuthProvider - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)()](./auth.githubauthprovider.md#githubauthproviderconstructor) | | Constructs a new instance of the GithubAuthProvider class | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [GITHUB\_SIGN\_IN\_METHOD](./auth.githubauthprovider.md#githubauthprovidergithub_sign_in_method) | static | 'github.com' | Always set to [SignInMethod](./auth.md#signinmethod).GITHUB. | -| [PROVIDER\_ID](./auth.githubauthprovider.md#githubauthproviderprovider_id) | static | 'github.com' | Always set to [ProviderId](./auth.md#providerid).GITHUB. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [credential(accessToken)](./auth.githubauthprovider.md#githubauthprovidercredential) | static | Creates a credential for Github. | -| [credentialFromError(error)](./auth.githubauthprovider.md#githubauthprovidercredentialfromerror) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. | -| [credentialFromResult(userCredential)](./auth.githubauthprovider.md#githubauthprovidercredentialfromresult) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). | - -## GithubAuthProvider.(constructor) - -Constructs a new instance of the `GithubAuthProvider` class - -Signature: - -```typescript -constructor(); -``` - -## GithubAuthProvider.GITHUB\_SIGN\_IN\_METHOD - -Always set to [SignInMethod](./auth.md#signinmethod).GITHUB. - -Signature: - -```typescript -static readonly GITHUB_SIGN_IN_METHOD: 'github.com'; -``` - -## GithubAuthProvider.PROVIDER\_ID - -Always set to [ProviderId](./auth.md#providerid).GITHUB. - -Signature: - -```typescript -static readonly PROVIDER_ID: 'github.com'; -``` - -## GithubAuthProvider.credential() - -Creates a credential for Github. - -Signature: - -```typescript -static credential(accessToken: string): OAuthCredential; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| accessToken | string | Github access token. | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) - -## GithubAuthProvider.credentialFromError() - -Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. - -Signature: - -```typescript -static credentialFromError(error: FirebaseError): OAuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null - -## GithubAuthProvider.credentialFromResult() - -Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). - -Signature: - -```typescript -static credentialFromResult(userCredential: UserCredential): OAuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null - -### Example 1 - - -```javascript -// Sign in using a redirect. -const provider = new GithubAuthProvider(); -// Start a sign in process for an unauthenticated user. -provider.addScope('repo'); -await signInWithRedirect(auth, provider); -// This will trigger a full page redirect away from your app - -// After returning from the redirect when your app initializes you can obtain the result -const result = await getRedirectResult(auth); -if (result) { - // This is the signed-in user - const user = result.user; - // This gives you a Github Access Token. - const credential = GithubAuthProvider.credentialFromResult(result); - const token = credential.accessToken; -} - -``` - -### Example 2 - - -```javascript -// Sign in using a popup. -const provider = new GithubAuthProvider(); -provider.addScope('repo'); -const result = await signInWithPopup(auth, provider); - -// The signed-in user info. -const user = result.user; -// This gives you a Github Access Token. -const credential = GithubAuthProvider.credentialFromResult(result); -const token = credential.accessToken; - -``` - diff --git a/docs-devsite/auth.googleauthprovider.md b/docs-devsite/auth.googleauthprovider.md deleted file mode 100644 index 2e14c0ff88e..00000000000 --- a/docs-devsite/auth.googleauthprovider.md +++ /dev/null @@ -1,185 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# GoogleAuthProvider class -Provider for generating an an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).GOOGLE. - -Signature: - -```typescript -export declare class GoogleAuthProvider extends BaseOAuthProvider -``` -Extends: BaseOAuthProvider - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)()](./auth.googleauthprovider.md#googleauthproviderconstructor) | | Constructs a new instance of the GoogleAuthProvider class | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [GOOGLE\_SIGN\_IN\_METHOD](./auth.googleauthprovider.md#googleauthprovidergoogle_sign_in_method) | static | 'google.com' | Always set to [SignInMethod](./auth.md#signinmethod).GOOGLE. | -| [PROVIDER\_ID](./auth.googleauthprovider.md#googleauthproviderprovider_id) | static | 'google.com' | Always set to [ProviderId](./auth.md#providerid).GOOGLE. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [credential(idToken, accessToken)](./auth.googleauthprovider.md#googleauthprovidercredential) | static | Creates a credential for Google. At least one of ID token and access token is required. | -| [credentialFromError(error)](./auth.googleauthprovider.md#googleauthprovidercredentialfromerror) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. | -| [credentialFromResult(userCredential)](./auth.googleauthprovider.md#googleauthprovidercredentialfromresult) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). | - -## GoogleAuthProvider.(constructor) - -Constructs a new instance of the `GoogleAuthProvider` class - -Signature: - -```typescript -constructor(); -``` - -## GoogleAuthProvider.GOOGLE\_SIGN\_IN\_METHOD - -Always set to [SignInMethod](./auth.md#signinmethod).GOOGLE. - -Signature: - -```typescript -static readonly GOOGLE_SIGN_IN_METHOD: 'google.com'; -``` - -## GoogleAuthProvider.PROVIDER\_ID - -Always set to [ProviderId](./auth.md#providerid).GOOGLE. - -Signature: - -```typescript -static readonly PROVIDER_ID: 'google.com'; -``` - -## GoogleAuthProvider.credential() - -Creates a credential for Google. At least one of ID token and access token is required. - -Signature: - -```typescript -static credential(idToken?: string | null, accessToken?: string | null): OAuthCredential; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| idToken | string \| null | Google ID token. | -| accessToken | string \| null | Google access token. | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) - -### Example - - -```javascript -// \`googleUser\` from the onsuccess Google Sign In callback. -const credential = GoogleAuthProvider.credential(googleUser.getAuthResponse().id_token); -const result = await signInWithCredential(credential); - -``` - -## GoogleAuthProvider.credentialFromError() - -Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. - -Signature: - -```typescript -static credentialFromError(error: FirebaseError): OAuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null - -## GoogleAuthProvider.credentialFromResult() - -Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). - -Signature: - -```typescript -static credentialFromResult(userCredential: UserCredential): OAuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null - -### Example 1 - - -```javascript -// Sign in using a redirect. -const provider = new GoogleAuthProvider(); -// Start a sign in process for an unauthenticated user. -provider.addScope('profile'); -provider.addScope('email'); -await signInWithRedirect(auth, provider); -// This will trigger a full page redirect away from your app - -// After returning from the redirect when your app initializes you can obtain the result -const result = await getRedirectResult(auth); -if (result) { - // This is the signed-in user - const user = result.user; - // This gives you a Google Access Token. - const credential = GoogleAuthProvider.credentialFromResult(result); - const token = credential.accessToken; -} - -``` - -### Example 2 - - -```javascript -// Sign in using a popup. -const provider = new GoogleAuthProvider(); -provider.addScope('profile'); -provider.addScope('email'); -const result = await signInWithPopup(auth, provider); - -// The signed-in user info. -const user = result.user; -// This gives you a Google Access Token. -const credential = GoogleAuthProvider.credentialFromResult(result); -const token = credential.accessToken; - -``` - diff --git a/docs-devsite/auth.idtokenresult.md b/docs-devsite/auth.idtokenresult.md deleted file mode 100644 index f000df924d9..00000000000 --- a/docs-devsite/auth.idtokenresult.md +++ /dev/null @@ -1,109 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# IdTokenResult interface -Interface representing ID token result obtained from [User.getIdTokenResult()](./auth.user.md#usergetidtokenresult). - -`IdTokenResult` contains the ID token JWT string and other helper properties for getting different data associated with the token as well as all the decoded payload claims. - -Note that these claims are not to be trusted as they are parsed client side. Only server side verification can guarantee the integrity of the token claims. - -Signature: - -```typescript -export interface IdTokenResult -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [authTime](./auth.idtokenresult.md#idtokenresultauthtime) | string | The authentication time formatted as a UTC string. | -| [claims](./auth.idtokenresult.md#idtokenresultclaims) | [ParsedToken](./auth.parsedtoken.md#parsedtoken_interface) | The entire payload claims of the ID token including the standard reserved claims as well as the custom claims. | -| [expirationTime](./auth.idtokenresult.md#idtokenresultexpirationtime) | string | The ID token expiration time formatted as a UTC string. | -| [issuedAtTime](./auth.idtokenresult.md#idtokenresultissuedattime) | string | The ID token issuance time formatted as a UTC string. | -| [signInProvider](./auth.idtokenresult.md#idtokenresultsigninprovider) | string \| null | The sign-in provider through which the ID token was obtained (anonymous, custom, phone, password, etc). | -| [signInSecondFactor](./auth.idtokenresult.md#idtokenresultsigninsecondfactor) | string \| null | The type of second factor associated with this session, provided the user was multi-factor authenticated (eg. phone, etc). | -| [token](./auth.idtokenresult.md#idtokenresulttoken) | string | The Firebase Auth ID token JWT string. | - -## IdTokenResult.authTime - -The authentication time formatted as a UTC string. - -This is the time the user authenticated (signed in) and not the time the token was refreshed. - -Signature: - -```typescript -authTime: string; -``` - -## IdTokenResult.claims - -The entire payload claims of the ID token including the standard reserved claims as well as the custom claims. - -Signature: - -```typescript -claims: ParsedToken; -``` - -## IdTokenResult.expirationTime - -The ID token expiration time formatted as a UTC string. - -Signature: - -```typescript -expirationTime: string; -``` - -## IdTokenResult.issuedAtTime - -The ID token issuance time formatted as a UTC string. - -Signature: - -```typescript -issuedAtTime: string; -``` - -## IdTokenResult.signInProvider - -The sign-in provider through which the ID token was obtained (anonymous, custom, phone, password, etc). - -Note, this does not map to provider IDs. - -Signature: - -```typescript -signInProvider: string | null; -``` - -## IdTokenResult.signInSecondFactor - -The type of second factor associated with this session, provided the user was multi-factor authenticated (eg. phone, etc). - -Signature: - -```typescript -signInSecondFactor: string | null; -``` - -## IdTokenResult.token - -The Firebase Auth ID token JWT string. - -Signature: - -```typescript -token: string; -``` diff --git a/docs-devsite/auth.md b/docs-devsite/auth.md deleted file mode 100644 index f0f9029c225..00000000000 --- a/docs-devsite/auth.md +++ /dev/null @@ -1,1992 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# auth package -Firebase Authentication - -## Functions - -| Function | Description | -| --- | --- | -| function(app...) | -| [getAuth(app)](./auth.md#getauth) | Returns the Auth instance associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). If no instance exists, initializes an Auth instance with platform-specific default dependencies. | -| [initializeAuth(app, deps)](./auth.md#initializeauth) | Initializes an [Auth](./auth.auth.md#auth_interface) instance with fine-grained control over [Dependencies](./auth.dependencies.md#dependencies_interface). | -| function(storage...) | -| [getReactNativePersistence(storage)](./auth.md#getreactnativepersistence) | Returns a persistence object that wraps AsyncStorage imported from react-native or @react-native-community/async-storage, and can be used in the persistence dependency field in [initializeAuth()](./auth.md#initializeauth). | -| function(auth...) | -| [applyActionCode(auth, oobCode)](./auth.md#applyactioncode) | Applies a verification code sent to the user by email or other out-of-band mechanism. | -| [beforeAuthStateChanged(auth, callback, onAbort)](./auth.md#beforeauthstatechanged) | Adds a blocking callback that runs before an auth state change sets a new user. | -| [checkActionCode(auth, oobCode)](./auth.md#checkactioncode) | Checks a verification code sent to the user by email or other out-of-band mechanism. | -| [confirmPasswordReset(auth, oobCode, newPassword)](./auth.md#confirmpasswordreset) | Completes the password reset process, given a confirmation code and new password. | -| [connectAuthEmulator(auth, url, options)](./auth.md#connectauthemulator) | Changes the [Auth](./auth.auth.md#auth_interface) instance to communicate with the Firebase Auth Emulator, instead of production Firebase Auth services. | -| [createUserWithEmailAndPassword(auth, email, password)](./auth.md#createuserwithemailandpassword) | Creates a new user account associated with the specified email address and password. | -| [fetchSignInMethodsForEmail(auth, email)](./auth.md#fetchsigninmethodsforemail) | Gets the list of possible sign in methods for the given email address. | -| [getMultiFactorResolver(auth, error)](./auth.md#getmultifactorresolver) | Provides a [MultiFactorResolver](./auth.multifactorresolver.md#multifactorresolver_interface) suitable for completion of a multi-factor flow. | -| [getRedirectResult(auth, resolver)](./auth.md#getredirectresult) | Returns a [UserCredential](./auth.usercredential.md#usercredential_interface) from the redirect-based sign-in flow. | -| [isSignInWithEmailLink(auth, emailLink)](./auth.md#issigninwithemaillink) | Checks if an incoming link is a sign-in with email link suitable for [signInWithEmailLink()](./auth.md#signinwithemaillink). | -| [onAuthStateChanged(auth, nextOrObserver, error, completed)](./auth.md#onauthstatechanged) | Adds an observer for changes to the user's sign-in state. | -| [onIdTokenChanged(auth, nextOrObserver, error, completed)](./auth.md#onidtokenchanged) | Adds an observer for changes to the signed-in user's ID token. | -| [sendPasswordResetEmail(auth, email, actionCodeSettings)](./auth.md#sendpasswordresetemail) | Sends a password reset email to the given email address. | -| [sendSignInLinkToEmail(auth, email, actionCodeSettings)](./auth.md#sendsigninlinktoemail) | Sends a sign-in email link to the user with the specified email. | -| [setPersistence(auth, persistence)](./auth.md#setpersistence) | Changes the type of persistence on the [Auth](./auth.auth.md#auth_interface) instance for the currently saved Auth session and applies this type of persistence for future sign-in requests, including sign-in with redirect requests. | -| [signInAnonymously(auth)](./auth.md#signinanonymously) | Asynchronously signs in as an anonymous user. | -| [signInWithCredential(auth, credential)](./auth.md#signinwithcredential) | Asynchronously signs in with the given credentials. | -| [signInWithCustomToken(auth, customToken)](./auth.md#signinwithcustomtoken) | Asynchronously signs in using a custom token. | -| [signInWithEmailAndPassword(auth, email, password)](./auth.md#signinwithemailandpassword) | Asynchronously signs in using an email and password. | -| [signInWithEmailLink(auth, email, emailLink)](./auth.md#signinwithemaillink) | Asynchronously signs in using an email and sign-in email link. | -| [signInWithPhoneNumber(auth, phoneNumber, appVerifier)](./auth.md#signinwithphonenumber) | Asynchronously signs in using a phone number. | -| [signInWithPopup(auth, provider, resolver)](./auth.md#signinwithpopup) | Authenticates a Firebase client using a popup-based OAuth authentication flow. | -| [signInWithRedirect(auth, provider, resolver)](./auth.md#signinwithredirect) | Authenticates a Firebase client using a full-page redirect flow. | -| [signOut(auth)](./auth.md#signout) | Signs out the current user. | -| [updateCurrentUser(auth, user)](./auth.md#updatecurrentuser) | Asynchronously sets the provided user as [Auth.currentUser](./auth.auth.md#authcurrentuser) on the [Auth](./auth.auth.md#auth_interface) instance. | -| [useDeviceLanguage(auth)](./auth.md#usedevicelanguage) | Sets the current language to the default device/browser preference. | -| [verifyPasswordResetCode(auth, code)](./auth.md#verifypasswordresetcode) | Checks a password reset code sent to the user by email or other out-of-band mechanism. | -| function(link...) | -| [parseActionCodeURL(link)](./auth.md#parseactioncodeurl) | Parses the email action link string and returns an [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) if the link is valid, otherwise returns null. | -| function(user...) | -| [deleteUser(user)](./auth.md#deleteuser) | Deletes and signs out the user. | -| [getIdToken(user, forceRefresh)](./auth.md#getidtoken) | Returns a JSON Web Token (JWT) used to identify the user to a Firebase service. | -| [getIdTokenResult(user, forceRefresh)](./auth.md#getidtokenresult) | Returns a deserialized JSON Web Token (JWT) used to identitfy the user to a Firebase service. | -| [linkWithCredential(user, credential)](./auth.md#linkwithcredential) | Links the user account with the given credentials. | -| [linkWithPhoneNumber(user, phoneNumber, appVerifier)](./auth.md#linkwithphonenumber) | Links the user account with the given phone number. | -| [linkWithPopup(user, provider, resolver)](./auth.md#linkwithpopup) | Links the authenticated provider to the user account using a pop-up based OAuth flow. | -| [linkWithRedirect(user, provider, resolver)](./auth.md#linkwithredirect) | Links the [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) to the user account using a full-page redirect flow. | -| [multiFactor(user)](./auth.md#multifactor) | The [MultiFactorUser](./auth.multifactoruser.md#multifactoruser_interface) corresponding to the user. | -| [reauthenticateWithCredential(user, credential)](./auth.md#reauthenticatewithcredential) | Re-authenticates a user using a fresh credential. | -| [reauthenticateWithPhoneNumber(user, phoneNumber, appVerifier)](./auth.md#reauthenticatewithphonenumber) | Re-authenticates a user using a fresh phone credential. | -| [reauthenticateWithPopup(user, provider, resolver)](./auth.md#reauthenticatewithpopup) | Reauthenticates the current user with the specified [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) using a pop-up based OAuth flow. | -| [reauthenticateWithRedirect(user, provider, resolver)](./auth.md#reauthenticatewithredirect) | Reauthenticates the current user with the specified [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) using a full-page redirect flow. | -| [reload(user)](./auth.md#reload) | Reloads user account data, if signed in. | -| [sendEmailVerification(user, actionCodeSettings)](./auth.md#sendemailverification) | Sends a verification email to a user. | -| [unlink(user, providerId)](./auth.md#unlink) | Unlinks a provider from a user account. | -| [updateEmail(user, newEmail)](./auth.md#updateemail) | Updates the user's email address. | -| [updatePassword(user, newPassword)](./auth.md#updatepassword) | Updates the user's password. | -| [updatePhoneNumber(user, credential)](./auth.md#updatephonenumber) | Updates the user's phone number. | -| [updateProfile(user, { displayName, photoURL: photoUrl })](./auth.md#updateprofile) | Updates a user's profile data. | -| [verifyBeforeUpdateEmail(user, newEmail, actionCodeSettings)](./auth.md#verifybeforeupdateemail) | Sends a verification email to a new email address. | -| function(userCredential...) | -| [getAdditionalUserInfo(userCredential)](./auth.md#getadditionaluserinfo) | Extracts provider specific [AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface) for the given credential. | - -## Classes - -| Class | Description | -| --- | --- | -| [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) | A utility class to parse email action URLs such as password reset, email verification, email link sign in, etc. | -| [AuthCredential](./auth.authcredential.md#authcredential_class) | Interface that represents the credentials returned by an [AuthProvider](./auth.authprovider.md#authprovider_interface). | -| [EmailAuthCredential](./auth.emailauthcredential.md#emailauthcredential_class) | Interface that represents the credentials returned by [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) for [ProviderId](./auth.md#providerid).PASSWORD | -| [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) | Provider for generating [EmailAuthCredential](./auth.emailauthcredential.md#emailauthcredential_class). | -| [FacebookAuthProvider](./auth.facebookauthprovider.md#facebookauthprovider_class) | Provider for generating an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).FACEBOOK. | -| [GithubAuthProvider](./auth.githubauthprovider.md#githubauthprovider_class) | Provider for generating an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).GITHUB. | -| [GoogleAuthProvider](./auth.googleauthprovider.md#googleauthprovider_class) | Provider for generating an an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).GOOGLE. | -| [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) | Represents the OAuth credentials returned by an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). | -| [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) | Provider for generating generic [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). | -| [PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class) | Represents the credentials returned by [PhoneAuthProvider](./auth.phoneauthprovider.md#phoneauthprovider_class). | -| [PhoneAuthProvider](./auth.phoneauthprovider.md#phoneauthprovider_class) | Provider for generating an [PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class). | -| [PhoneMultiFactorGenerator](./auth.phonemultifactorgenerator.md#phonemultifactorgenerator_class) | Provider for generating a [PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface). | -| [RecaptchaVerifier](./auth.recaptchaverifier.md#recaptchaverifier_class) | An [reCAPTCHA](https://www.google.com/recaptcha/)-based application verifier. | -| [SAMLAuthProvider](./auth.samlauthprovider.md#samlauthprovider_class) | An [AuthProvider](./auth.authprovider.md#authprovider_interface) for SAML. | -| [TwitterAuthProvider](./auth.twitterauthprovider.md#twitterauthprovider_class) | Provider for generating an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).TWITTER. | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [ActionCodeInfo](./auth.actioncodeinfo.md#actioncodeinfo_interface) | A response from [checkActionCode()](./auth.md#checkactioncode). | -| [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface) | An interface that defines the required continue/state URL with optional Android and iOS bundle identifiers. | -| [AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface) | A structure containing additional user information from a federated identity provider. | -| [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) | A verifier for domain verification and abuse prevention. | -| [Auth](./auth.auth.md#auth_interface) | Interface representing Firebase Auth service. | -| [AuthError](./auth.autherror.md#autherror_interface) | Interface for an Auth error. | -| [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) | A mapping of error codes to error messages. | -| [AuthProvider](./auth.authprovider.md#authprovider_interface) | Interface that represents an auth provider, used to facilitate creating [AuthCredential](./auth.authcredential.md#authcredential_class). | -| [AuthSettings](./auth.authsettings.md#authsettings_interface) | Interface representing an [Auth](./auth.auth.md#auth_interface) instance's settings. | -| [Config](./auth.config.md#config_interface) | Interface representing the Auth config. | -| [ConfirmationResult](./auth.confirmationresult.md#confirmationresult_interface) | A result from a phone number sign-in, link, or reauthenticate call. | -| [Dependencies](./auth.dependencies.md#dependencies_interface) | The dependencies that can be used to initialize an [Auth](./auth.auth.md#auth_interface) instance. | -| [EmulatorConfig](./auth.emulatorconfig.md#emulatorconfig_interface) | Configuration of Firebase Authentication Emulator. | -| [IdTokenResult](./auth.idtokenresult.md#idtokenresult_interface) | Interface representing ID token result obtained from [User.getIdTokenResult()](./auth.user.md#usergetidtokenresult). | -| [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) | The base class for asserting ownership of a second factor. | -| [MultiFactorError](./auth.multifactorerror.md#multifactorerror_interface) | The error thrown when the user needs to provide a second factor to sign in successfully. | -| [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) | A structure containing the information of a second factor entity. | -| [MultiFactorResolver](./auth.multifactorresolver.md#multifactorresolver_interface) | The class used to facilitate recovery from [MultiFactorError](./auth.multifactorerror.md#multifactorerror_interface) when a user needs to provide a second factor to sign in. | -| [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) | An interface defining the multi-factor session object used for enrolling a second factor on a user or helping sign in an enrolled user with a second factor. | -| [MultiFactorUser](./auth.multifactoruser.md#multifactoruser_interface) | An interface that defines the multi-factor related properties and operations pertaining to a [User](./auth.user.md#user_interface). | -| [OAuthCredentialOptions](./auth.oauthcredentialoptions.md#oauthcredentialoptions_interface) | Defines the options for initializing an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). | -| [ParsedToken](./auth.parsedtoken.md#parsedtoken_interface) | Interface representing a parsed ID token. | -| [Persistence](./auth.persistence.md#persistence_interface) | An interface covering the possible persistence mechanism types. | -| [PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface) | The class for asserting ownership of a phone second factor. Provided by [PhoneMultiFactorGenerator.assertion()](./auth.phonemultifactorgenerator.md#phonemultifactorgeneratorassertion). | -| [PhoneMultiFactorEnrollInfoOptions](./auth.phonemultifactorenrollinfooptions.md#phonemultifactorenrollinfooptions_interface) | Options used for enrolling a second factor. | -| [PhoneMultiFactorInfo](./auth.phonemultifactorinfo.md#phonemultifactorinfo_interface) | The subclass of the [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) interface for phone number second factors. The factorId of this second factor is [FactorId](./auth.md#factorid).PHONE. | -| [PhoneMultiFactorSignInInfoOptions](./auth.phonemultifactorsignininfooptions.md#phonemultifactorsignininfooptions_interface) | Options used for signing in with a second factor. | -| [PhoneSingleFactorInfoOptions](./auth.phonesinglefactorinfooptions.md#phonesinglefactorinfooptions_interface) | Options used for single-factor sign-in. | -| [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | A resolver used for handling DOM specific operations like [signInWithPopup()](./auth.md#signinwithpopup) or [signInWithRedirect()](./auth.md#signinwithredirect). | -| [ReactNativeAsyncStorage](./auth.reactnativeasyncstorage.md#reactnativeasyncstorage_interface) | Interface for a supplied AsyncStorage. | -| [RecaptchaParameters](./auth.recaptchaparameters.md#recaptchaparameters_interface) | Interface representing reCAPTCHA parameters.See the \[reCAPTCHA docs\](https://developers.google.com/recaptcha/docs/display\#render\_param) for the list of accepted parameters. All parameters are accepted except for sitekey: Firebase Auth provisions a reCAPTCHA for each project and will configure the site key upon rendering.For an invisible reCAPTCHA, set the size key to invisible. | -| [User](./auth.user.md#user_interface) | A user account. | -| [UserCredential](./auth.usercredential.md#usercredential_interface) | A structure containing a [User](./auth.user.md#user_interface), the [OperationType](./auth.md#operationtype), and the provider ID. | -| [UserInfo](./auth.userinfo.md#userinfo_interface) | User profile information, visible only to the Firebase project's apps. | -| [UserMetadata](./auth.usermetadata.md#usermetadata_interface) | Interface representing a user's metadata. | - -## Variables - -| Variable | Description | -| --- | --- | -| [ActionCodeOperation](./auth.md#actioncodeoperation) | An enumeration of the possible email action types. | -| [AuthErrorCodes](./auth.md#autherrorcodes) | A map of potential Auth error codes, for easier comparison with errors thrown by the SDK. | -| [browserLocalPersistence](./auth.md#browserlocalpersistence) | An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type LOCAL using localStorage for the underlying storage. | -| [browserPopupRedirectResolver](./auth.md#browserpopupredirectresolver) | An implementation of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) suitable for browser based applications. | -| [browserSessionPersistence](./auth.md#browsersessionpersistence) | An implementation of [Persistence](./auth.persistence.md#persistence_interface) of SESSION using sessionStorage for the underlying storage. | -| [cordovaPopupRedirectResolver](./auth.md#cordovapopupredirectresolver) | An implementation of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) suitable for Cordova based applications. | -| [debugErrorMap](./auth.md#debugerrormap) | A verbose error map with detailed descriptions for most error codes.See discussion at [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) | -| [FactorId](./auth.md#factorid) | An enum of factors that may be used for multifactor authentication. | -| [indexedDBLocalPersistence](./auth.md#indexeddblocalpersistence) | An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type LOCAL using indexedDB for the underlying storage. | -| [inMemoryPersistence](./auth.md#inmemorypersistence) | An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type 'NONE'. | -| [OperationType](./auth.md#operationtype) | Enumeration of supported operation types. | -| [prodErrorMap](./auth.md#proderrormap) | A minimal error map with all verbose error messages stripped.See discussion at [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) | -| [ProviderId](./auth.md#providerid) | Enumeration of supported providers. | -| [reactNativeLocalPersistence](./auth.md#reactnativelocalpersistence) | An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type 'LOCAL' for use in React Native environments. | -| [SignInMethod](./auth.md#signinmethod) | Enumeration of supported sign-in methods. | - -## Type Aliases - -| Type Alias | Description | -| --- | --- | -| [CustomParameters](./auth.md#customparameters) | Map of OAuth Custom Parameters. | -| [NextOrObserver](./auth.md#nextorobserver) | Type definition for an event callback. | -| [PhoneInfoOptions](./auth.md#phoneinfooptions) | The information required to verify the ownership of a phone number. | -| [UserProfile](./auth.md#userprofile) | User profile used in [AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface). | - -## getAuth() - -Returns the Auth instance associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). If no instance exists, initializes an Auth instance with platform-specific default dependencies. - -Signature: - -```typescript -export declare function getAuth(app?: FirebaseApp): Auth; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The Firebase App. | - -Returns: - -[Auth](./auth.auth.md#auth_interface) - -## initializeAuth() - -Initializes an [Auth](./auth.auth.md#auth_interface) instance with fine-grained control over [Dependencies](./auth.dependencies.md#dependencies_interface). - -This function allows more control over the [Auth](./auth.auth.md#auth_interface) instance than [getAuth()](./auth.md#getauth). `getAuth` uses platform-specific defaults to supply the [Dependencies](./auth.dependencies.md#dependencies_interface). In general, `getAuth` is the easiest way to initialize Auth and works for most use cases. Use `initializeAuth` if you need control over which persistence layer is used, or to minimize bundle size if you're not using either `signInWithPopup` or `signInWithRedirect`. - -For example, if your app only uses anonymous accounts and you only want accounts saved for the current session, initialize `Auth` with: - -```js -const auth = initializeAuth(app, { - persistence: browserSessionPersistence, - popupRedirectResolver: undefined, -}); - -``` - -Signature: - -```typescript -export declare function initializeAuth(app: FirebaseApp, deps?: Dependencies): Auth; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | | -| deps | [Dependencies](./auth.dependencies.md#dependencies_interface) | | - -Returns: - -[Auth](./auth.auth.md#auth_interface) - -## getReactNativePersistence() - -Returns a persistence object that wraps `AsyncStorage` imported from `react-native` or `@react-native-community/async-storage`, and can be used in the persistence dependency field in [initializeAuth()](./auth.md#initializeauth). - -Signature: - -```typescript -export declare function getReactNativePersistence(storage: ReactNativeAsyncStorage): Persistence; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| storage | [ReactNativeAsyncStorage](./auth.reactnativeasyncstorage.md#reactnativeasyncstorage_interface) | | - -Returns: - -[Persistence](./auth.persistence.md#persistence_interface) - -## applyActionCode() - -Applies a verification code sent to the user by email or other out-of-band mechanism. - -Signature: - -```typescript -export declare function applyActionCode(auth: Auth, oobCode: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| oobCode | string | A verification code sent to the user. | - -Returns: - -Promise<void> - -## beforeAuthStateChanged() - -Adds a blocking callback that runs before an auth state change sets a new user. - -Signature: - -```typescript -export declare function beforeAuthStateChanged(auth: Auth, callback: (user: User | null) => void | Promise, onAbort?: () => void): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| callback | (user: [User](./auth.user.md#user_interface) \| null) => void \| Promise<void> | callback triggered before new user value is set. If this throws, it blocks the user from being set. | -| onAbort | () => void | callback triggered if a later beforeAuthStateChanged() callback throws, allowing you to undo any side effects. | - -Returns: - -[Unsubscribe](./util.md#unsubscribe) - -## checkActionCode() - -Checks a verification code sent to the user by email or other out-of-band mechanism. - -Signature: - -```typescript -export declare function checkActionCode(auth: Auth, oobCode: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| oobCode | string | A verification code sent to the user. | - -Returns: - -Promise<[ActionCodeInfo](./auth.actioncodeinfo.md#actioncodeinfo_interface)> - -metadata about the code. - -## confirmPasswordReset() - -Completes the password reset process, given a confirmation code and new password. - -Signature: - -```typescript -export declare function confirmPasswordReset(auth: Auth, oobCode: string, newPassword: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| oobCode | string | A confirmation code sent to the user. | -| newPassword | string | The new password. | - -Returns: - -Promise<void> - -## connectAuthEmulator() - -Changes the [Auth](./auth.auth.md#auth_interface) instance to communicate with the Firebase Auth Emulator, instead of production Firebase Auth services. - -This must be called synchronously immediately following the first call to [initializeAuth()](./auth.md#initializeauth). Do not use with production credentials as emulator traffic is not encrypted. - -Signature: - -```typescript -export declare function connectAuthEmulator(auth: Auth, url: string, options?: { - disableWarnings: boolean; -}): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| url | string | The URL at which the emulator is running (eg, 'http://localhost:9099'). | -| options | { disableWarnings: boolean; } | Optional. options.disableWarnings defaults to false. Set it to true to disable the warning banner attached to the DOM. | - -Returns: - -void - -### Example - - -```javascript -connectAuthEmulator(auth, 'http://127.0.0.1:9099', { disableWarnings: true }); - -``` - -## createUserWithEmailAndPassword() - -Creates a new user account associated with the specified email address and password. - -On successful creation of the user account, this user will also be signed in to your application. - -User account creation can fail if the account already exists or the password is invalid. - -Note: The email address acts as a unique identifier for the user and enables an email-based password reset. This function will create a new user account and set the initial user password. - -Signature: - -```typescript -export declare function createUserWithEmailAndPassword(auth: Auth, email: string, password: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| email | string | The user's email address. | -| password | string | The user's chosen password. | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -## fetchSignInMethodsForEmail() - -Gets the list of possible sign in methods for the given email address. - -This is useful to differentiate methods of sign-in for the same provider, eg. [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) which has 2 methods of sign-in, [SignInMethod](./auth.md#signinmethod).EMAIL\_PASSWORD and [SignInMethod](./auth.md#signinmethod).EMAIL\_LINK. - -Signature: - -```typescript -export declare function fetchSignInMethodsForEmail(auth: Auth, email: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| email | string | The user's email address. | - -Returns: - -Promise<string\[\]> - -## getMultiFactorResolver() - -Provides a [MultiFactorResolver](./auth.multifactorresolver.md#multifactorresolver_interface) suitable for completion of a multi-factor flow. - -Signature: - -```typescript -export declare function getMultiFactorResolver(auth: Auth, error: MultiFactorError): MultiFactorResolver; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| error | [MultiFactorError](./auth.multifactorerror.md#multifactorerror_interface) | The [MultiFactorError](./auth.multifactorerror.md#multifactorerror_interface) raised during a sign-in, or reauthentication operation. | - -Returns: - -[MultiFactorResolver](./auth.multifactorresolver.md#multifactorresolver_interface) - -## getRedirectResult() - -Returns a [UserCredential](./auth.usercredential.md#usercredential_interface) from the redirect-based sign-in flow. - -If sign-in succeeded, returns the signed in user. If sign-in was unsuccessful, fails with an error. If no redirect operation was called, returns `null`. - -Signature: - -```typescript -export declare function getRedirectResult(auth: Auth, resolver?: PopupRedirectResolver): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface) \| null> - -### Example - - -```javascript -// Sign in using a redirect. -const provider = new FacebookAuthProvider(); -// You can add additional scopes to the provider: -provider.addScope('user_birthday'); -// Start a sign in process for an unauthenticated user. -await signInWithRedirect(auth, provider); -// This will trigger a full page redirect away from your app - -// After returning from the redirect when your app initializes you can obtain the result -const result = await getRedirectResult(auth); -if (result) { - // This is the signed-in user - const user = result.user; - // This gives you a Facebook Access Token. - const credential = provider.credentialFromResult(auth, result); - const token = credential.accessToken; -} -// As this API can be used for sign-in, linking and reauthentication, -// check the operationType to determine what triggered this redirect -// operation. -const operationType = result.operationType; - -``` - -## isSignInWithEmailLink() - -Checks if an incoming link is a sign-in with email link suitable for [signInWithEmailLink()](./auth.md#signinwithemaillink). - -Signature: - -```typescript -export declare function isSignInWithEmailLink(auth: Auth, emailLink: string): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| emailLink | string | The link sent to the user's email address. | - -Returns: - -boolean - -## onAuthStateChanged() - -Adds an observer for changes to the user's sign-in state. - -To keep the old behavior, see [onIdTokenChanged()](./auth.md#onidtokenchanged). - -Signature: - -```typescript -export declare function onAuthStateChanged(auth: Auth, nextOrObserver: NextOrObserver, error?: ErrorFn, completed?: CompleteFn): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| nextOrObserver | [NextOrObserver](./auth.md#nextorobserver)<[User](./auth.user.md#user_interface)> | callback triggered on change. | -| error | [ErrorFn](./util.md#errorfn) | Deprecated. This callback is never triggered. Errors on signing in/out can be caught in promises returned from sign-in/sign-out functions. | -| completed | [CompleteFn](./util.md#completefn) | Deprecated. This callback is never triggered. | - -Returns: - -[Unsubscribe](./util.md#unsubscribe) - -## onIdTokenChanged() - -Adds an observer for changes to the signed-in user's ID token. - -This includes sign-in, sign-out, and token refresh events. - -Signature: - -```typescript -export declare function onIdTokenChanged(auth: Auth, nextOrObserver: NextOrObserver, error?: ErrorFn, completed?: CompleteFn): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| nextOrObserver | [NextOrObserver](./auth.md#nextorobserver)<[User](./auth.user.md#user_interface)> | callback triggered on change. | -| error | [ErrorFn](./util.md#errorfn) | Deprecated. This callback is never triggered. Errors on signing in/out can be caught in promises returned from sign-in/sign-out functions. | -| completed | [CompleteFn](./util.md#completefn) | Deprecated. This callback is never triggered. | - -Returns: - -[Unsubscribe](./util.md#unsubscribe) - -## sendPasswordResetEmail() - -Sends a password reset email to the given email address. - -To complete the password reset, call [confirmPasswordReset()](./auth.md#confirmpasswordreset) with the code supplied in the email sent to the user, along with the new password specified by the user. - -Signature: - -```typescript -export declare function sendPasswordResetEmail(auth: Auth, email: string, actionCodeSettings?: ActionCodeSettings): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| email | string | The user's email address. | -| actionCodeSettings | [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface) | The [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface). | - -Returns: - -Promise<void> - -### Example - - -```javascript -const actionCodeSettings = { - url: 'https://www.example.com/?email=user@example.com', - iOS: { - bundleId: 'com.example.ios' - }, - android: { - packageName: 'com.example.android', - installApp: true, - minimumVersion: '12' - }, - handleCodeInApp: true -}; -await sendPasswordResetEmail(auth, 'user@example.com', actionCodeSettings); -// Obtain code from user. -await confirmPasswordReset('user@example.com', code); - -``` - -## sendSignInLinkToEmail() - -Sends a sign-in email link to the user with the specified email. - -The sign-in operation has to always be completed in the app unlike other out of band email actions (password reset and email verifications). This is because, at the end of the flow, the user is expected to be signed in and their Auth state persisted within the app. - -To complete sign in with the email link, call [signInWithEmailLink()](./auth.md#signinwithemaillink) with the email address and the email link supplied in the email sent to the user. - -Signature: - -```typescript -export declare function sendSignInLinkToEmail(auth: Auth, email: string, actionCodeSettings: ActionCodeSettings): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | | -| email | string | The user's email address. | -| actionCodeSettings | [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface) | The [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface). | - -Returns: - -Promise<void> - -### Example - - -```javascript -const actionCodeSettings = { - url: 'https://www.example.com/?email=user@example.com', - iOS: { - bundleId: 'com.example.ios' - }, - android: { - packageName: 'com.example.android', - installApp: true, - minimumVersion: '12' - }, - handleCodeInApp: true -}; -await sendSignInLinkToEmail(auth, 'user@example.com', actionCodeSettings); -// Obtain emailLink from the user. -if(isSignInWithEmailLink(auth, emailLink)) { - await signInWithEmailLink(auth, 'user@example.com', emailLink); -} - -``` - -## setPersistence() - -Changes the type of persistence on the [Auth](./auth.auth.md#auth_interface) instance for the currently saved `Auth` session and applies this type of persistence for future sign-in requests, including sign-in with redirect requests. - -This makes it easy for a user signing in to specify whether their session should be remembered or not. It also makes it easier to never persist the `Auth` state for applications that are shared by other users or have sensitive data. - -Signature: - -```typescript -export declare function setPersistence(auth: Auth, persistence: Persistence): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| persistence | [Persistence](./auth.persistence.md#persistence_interface) | The [Persistence](./auth.persistence.md#persistence_interface) to use. | - -Returns: - -Promise<void> - -A `Promise` that resolves once the persistence change has completed - -### Example - - -```javascript -setPersistence(auth, browserSessionPersistence); - -``` - -## signInAnonymously() - -Asynchronously signs in as an anonymous user. - -If there is already an anonymous user signed in, that user will be returned; otherwise, a new anonymous user identity will be created and returned. - -Signature: - -```typescript -export declare function signInAnonymously(auth: Auth): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -## signInWithCredential() - -Asynchronously signs in with the given credentials. - -An [AuthProvider](./auth.authprovider.md#authprovider_interface) can be used to generate the credential. - -Signature: - -```typescript -export declare function signInWithCredential(auth: Auth, credential: AuthCredential): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| credential | [AuthCredential](./auth.authcredential.md#authcredential_class) | The auth credential. | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -## signInWithCustomToken() - -Asynchronously signs in using a custom token. - -Custom tokens are used to integrate Firebase Auth with existing auth systems, and must be generated by an auth backend using the [createCustomToken](https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#createcustomtoken) method in the [Admin SDK](https://firebase.google.com/docs/auth/admin) . - -Fails with an error if the token is invalid, expired, or not accepted by the Firebase Auth service. - -Signature: - -```typescript -export declare function signInWithCustomToken(auth: Auth, customToken: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| customToken | string | The custom token to sign in with. | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -## signInWithEmailAndPassword() - -Asynchronously signs in using an email and password. - -Fails with an error if the email address and password do not match. - -Note: The user's password is NOT the password used to access the user's email account. The email address serves as a unique identifier for the user, and the password is used to access the user's account in your Firebase project. See also: [createUserWithEmailAndPassword()](./auth.md#createuserwithemailandpassword). - -Signature: - -```typescript -export declare function signInWithEmailAndPassword(auth: Auth, email: string, password: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| email | string | The users email address. | -| password | string | The users password. | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -## signInWithEmailLink() - -Asynchronously signs in using an email and sign-in email link. - -If no link is passed, the link is inferred from the current URL. - -Fails with an error if the email address is invalid or OTP in email link expires. - -Note: Confirm the link is a sign-in email link before calling this method firebase.auth.Auth.isSignInWithEmailLink. - -Signature: - -```typescript -export declare function signInWithEmailLink(auth: Auth, email: string, emailLink?: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| email | string | The user's email address. | -| emailLink | string | The link sent to the user's email address. | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -### Example - - -```javascript -const actionCodeSettings = { - url: 'https://www.example.com/?email=user@example.com', - iOS: { - bundleId: 'com.example.ios' - }, - android: { - packageName: 'com.example.android', - installApp: true, - minimumVersion: '12' - }, - handleCodeInApp: true -}; -await sendSignInLinkToEmail(auth, 'user@example.com', actionCodeSettings); -// Obtain emailLink from the user. -if(isSignInWithEmailLink(auth, emailLink)) { - await signInWithEmailLink(auth, 'user@example.com', emailLink); -} - -``` - -## signInWithPhoneNumber() - -Asynchronously signs in using a phone number. - -This method sends a code via SMS to the given phone number, and returns a [ConfirmationResult](./auth.confirmationresult.md#confirmationresult_interface). After the user provides the code sent to their phone, call [ConfirmationResult.confirm()](./auth.confirmationresult.md#confirmationresultconfirm) with the code to sign the user in. - -For abuse prevention, this method also requires a [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface). This SDK includes a reCAPTCHA-based implementation, [RecaptchaVerifier](./auth.recaptchaverifier.md#recaptchaverifier_class). This function can work on other platforms that do not support the [RecaptchaVerifier](./auth.recaptchaverifier.md#recaptchaverifier_class) (like React Native), but you need to use a third-party [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) implementation. - -Signature: - -```typescript -export declare function signInWithPhoneNumber(auth: Auth, phoneNumber: string, appVerifier: ApplicationVerifier): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| phoneNumber | string | The user's phone number in E.164 format (e.g. +16505550101). | -| appVerifier | [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) | The [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface). | - -Returns: - -Promise<[ConfirmationResult](./auth.confirmationresult.md#confirmationresult_interface)> - -### Example - - -```javascript -// 'recaptcha-container' is the ID of an element in the DOM. -const applicationVerifier = new firebase.auth.RecaptchaVerifier('recaptcha-container'); -const confirmationResult = await signInWithPhoneNumber(auth, phoneNumber, applicationVerifier); -// Obtain a verificationCode from the user. -const credential = await confirmationResult.confirm(verificationCode); - -``` - -## signInWithPopup() - -Authenticates a Firebase client using a popup-based OAuth authentication flow. - -If succeeds, returns the signed in user along with the provider's credential. If sign in was unsuccessful, returns an error object containing additional information about the error. - -Signature: - -```typescript -export declare function signInWithPopup(auth: Auth, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | -| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -### Example - - -```javascript -// Sign in using a popup. -const provider = new FacebookAuthProvider(); -const result = await signInWithPopup(auth, provider); - -// The signed-in user info. -const user = result.user; -// This gives you a Facebook Access Token. -const credential = provider.credentialFromResult(auth, result); -const token = credential.accessToken; - -``` - -## signInWithRedirect() - -Authenticates a Firebase client using a full-page redirect flow. - -To handle the results and errors for this operation, refer to [getRedirectResult()](./auth.md#getredirectresult). Follow the [best practices](https://firebase.google.com/docs/auth/web/redirect-best-practices) when using [signInWithRedirect()](./auth.md#signinwithredirect). - -Signature: - -```typescript -export declare function signInWithRedirect(auth: Auth, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | -| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | - -Returns: - -Promise<never> - -### Example - - -```javascript -// Sign in using a redirect. -const provider = new FacebookAuthProvider(); -// You can add additional scopes to the provider: -provider.addScope('user_birthday'); -// Start a sign in process for an unauthenticated user. -await signInWithRedirect(auth, provider); -// This will trigger a full page redirect away from your app - -// After returning from the redirect when your app initializes you can obtain the result -const result = await getRedirectResult(auth); -if (result) { - // This is the signed-in user - const user = result.user; - // This gives you a Facebook Access Token. - const credential = provider.credentialFromResult(auth, result); - const token = credential.accessToken; -} -// As this API can be used for sign-in, linking and reauthentication, -// check the operationType to determine what triggered this redirect -// operation. -const operationType = result.operationType; - -``` - -## signOut() - -Signs out the current user. - -Signature: - -```typescript -export declare function signOut(auth: Auth): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | - -Returns: - -Promise<void> - -## updateCurrentUser() - -Asynchronously sets the provided user as [Auth.currentUser](./auth.auth.md#authcurrentuser) on the [Auth](./auth.auth.md#auth_interface) instance. - -A new instance copy of the user provided will be made and set as currentUser. - -This will trigger [onAuthStateChanged()](./auth.md#onauthstatechanged) and [onIdTokenChanged()](./auth.md#onidtokenchanged) listeners like other sign in methods. - -The operation fails with an error if the user to be updated belongs to a different Firebase project. - -Signature: - -```typescript -export declare function updateCurrentUser(auth: Auth, user: User | null): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| user | [User](./auth.user.md#user_interface) \| null | The new [User](./auth.user.md#user_interface). | - -Returns: - -Promise<void> - -## useDeviceLanguage() - -Sets the current language to the default device/browser preference. - -Signature: - -```typescript -export declare function useDeviceLanguage(auth: Auth): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | - -Returns: - -void - -## verifyPasswordResetCode() - -Checks a password reset code sent to the user by email or other out-of-band mechanism. - -Signature: - -```typescript -export declare function verifyPasswordResetCode(auth: Auth, code: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | -| code | string | A verification code sent to the user. | - -Returns: - -Promise<string> - -the user's email address if valid. - -## parseActionCodeURL() - -Parses the email action link string and returns an [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) if the link is valid, otherwise returns null. - -Signature: - -```typescript -export declare function parseActionCodeURL(link: string): ActionCodeURL | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| link | string | | - -Returns: - -[ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) \| null - -## deleteUser() - -Deletes and signs out the user. - -Important: this is a security-sensitive operation that requires the user to have recently signed in. If this requirement isn't met, ask the user to authenticate again and then call [reauthenticateWithCredential()](./auth.md#reauthenticatewithcredential). - -Signature: - -```typescript -export declare function deleteUser(user: User): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | - -Returns: - -Promise<void> - -## getIdToken() - -Returns a JSON Web Token (JWT) used to identify the user to a Firebase service. - -Returns the current token if it has not expired or if it will not expire in the next five minutes. Otherwise, this will refresh the token and return a new one. - -Signature: - -```typescript -export declare function getIdToken(user: User, forceRefresh?: boolean): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| forceRefresh | boolean | Force refresh regardless of token expiration. | - -Returns: - -Promise<string> - -## getIdTokenResult() - -Returns a deserialized JSON Web Token (JWT) used to identitfy the user to a Firebase service. - -Returns the current token if it has not expired or if it will not expire in the next five minutes. Otherwise, this will refresh the token and return a new one. - -Signature: - -```typescript -export declare function getIdTokenResult(user: User, forceRefresh?: boolean): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| forceRefresh | boolean | Force refresh regardless of token expiration. | - -Returns: - -Promise<[IdTokenResult](./auth.idtokenresult.md#idtokenresult_interface)> - -## linkWithCredential() - -Links the user account with the given credentials. - -An [AuthProvider](./auth.authprovider.md#authprovider_interface) can be used to generate the credential. - -Signature: - -```typescript -export declare function linkWithCredential(user: User, credential: AuthCredential): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| credential | [AuthCredential](./auth.authcredential.md#authcredential_class) | The auth credential. | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -## linkWithPhoneNumber() - -Links the user account with the given phone number. - -Signature: - -```typescript -export declare function linkWithPhoneNumber(user: User, phoneNumber: string, appVerifier: ApplicationVerifier): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| phoneNumber | string | The user's phone number in E.164 format (e.g. +16505550101). | -| appVerifier | [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) | The [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface). | - -Returns: - -Promise<[ConfirmationResult](./auth.confirmationresult.md#confirmationresult_interface)> - -## linkWithPopup() - -Links the authenticated provider to the user account using a pop-up based OAuth flow. - -If the linking is successful, the returned result will contain the user and the provider's credential. - -Signature: - -```typescript -export declare function linkWithPopup(user: User, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | -| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -### Example - - -```javascript -// Sign in using some other provider. -const result = await signInWithEmailAndPassword(auth, email, password); -// Link using a popup. -const provider = new FacebookAuthProvider(); -await linkWithPopup(result.user, provider); - -``` - -## linkWithRedirect() - -Links the [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) to the user account using a full-page redirect flow. - -To handle the results and errors for this operation, refer to [getRedirectResult()](./auth.md#getredirectresult). Follow the [best practices](https://firebase.google.com/docs/auth/web/redirect-best-practices) when using [linkWithRedirect()](./auth.md#linkwithredirect). - -Signature: - -```typescript -export declare function linkWithRedirect(user: User, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | -| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | - -Returns: - -Promise<never> - -### Example - - -```javascript -// Sign in using some other provider. -const result = await signInWithEmailAndPassword(auth, email, password); -// Link using a redirect. -const provider = new FacebookAuthProvider(); -await linkWithRedirect(result.user, provider); -// This will trigger a full page redirect away from your app - -// After returning from the redirect when your app initializes you can obtain the result -const result = await getRedirectResult(auth); - -``` - -## multiFactor() - -The [MultiFactorUser](./auth.multifactoruser.md#multifactoruser_interface) corresponding to the user. - -This is used to access all multi-factor properties and operations related to the user. - -Signature: - -```typescript -export declare function multiFactor(user: User): MultiFactorUser; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | - -Returns: - -[MultiFactorUser](./auth.multifactoruser.md#multifactoruser_interface) - -## reauthenticateWithCredential() - -Re-authenticates a user using a fresh credential. - -Use before operations such as [updatePassword()](./auth.md#updatepassword) that require tokens from recent sign-in attempts. This method can be used to recover from a `CREDENTIAL_TOO_OLD_LOGIN_AGAIN` error or a `TOKEN_EXPIRED` error. - -Signature: - -```typescript -export declare function reauthenticateWithCredential(user: User, credential: AuthCredential): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| credential | [AuthCredential](./auth.authcredential.md#authcredential_class) | The auth credential. | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -## reauthenticateWithPhoneNumber() - -Re-authenticates a user using a fresh phone credential. - -Use before operations such as [updatePassword()](./auth.md#updatepassword) that require tokens from recent sign-in attempts. - -Signature: - -```typescript -export declare function reauthenticateWithPhoneNumber(user: User, phoneNumber: string, appVerifier: ApplicationVerifier): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| phoneNumber | string | The user's phone number in E.164 format (e.g. +16505550101). | -| appVerifier | [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) | The [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface). | - -Returns: - -Promise<[ConfirmationResult](./auth.confirmationresult.md#confirmationresult_interface)> - -## reauthenticateWithPopup() - -Reauthenticates the current user with the specified [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) using a pop-up based OAuth flow. - -If the reauthentication is successful, the returned result will contain the user and the provider's credential. - -Signature: - -```typescript -export declare function reauthenticateWithPopup(user: User, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | -| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -### Example - - -```javascript -// Sign in using a popup. -const provider = new FacebookAuthProvider(); -const result = await signInWithPopup(auth, provider); -// Reauthenticate using a popup. -await reauthenticateWithPopup(result.user, provider); - -``` - -## reauthenticateWithRedirect() - -Reauthenticates the current user with the specified [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) using a full-page redirect flow. - -To handle the results and errors for this operation, refer to [getRedirectResult()](./auth.md#getredirectresult). Follow the [best practices](https://firebase.google.com/docs/auth/web/redirect-best-practices) when using [reauthenticateWithRedirect()](./auth.md#reauthenticatewithredirect). - -Signature: - -```typescript -export declare function reauthenticateWithRedirect(user: User, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | -| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | - -Returns: - -Promise<never> - -### Example - - -```javascript -// Sign in using a redirect. -const provider = new FacebookAuthProvider(); -const result = await signInWithRedirect(auth, provider); -// This will trigger a full page redirect away from your app - -// After returning from the redirect when your app initializes you can obtain the result -const result = await getRedirectResult(auth); -// Reauthenticate using a redirect. -await reauthenticateWithRedirect(result.user, provider); -// This will again trigger a full page redirect away from your app - -// After returning from the redirect when your app initializes you can obtain the result -const result = await getRedirectResult(auth); - -``` - -## reload() - -Reloads user account data, if signed in. - -Signature: - -```typescript -export declare function reload(user: User): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | - -Returns: - -Promise<void> - -## sendEmailVerification() - -Sends a verification email to a user. - -The verification process is completed by calling [applyActionCode()](./auth.md#applyactioncode). - -Signature: - -```typescript -export declare function sendEmailVerification(user: User, actionCodeSettings?: ActionCodeSettings | null): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| actionCodeSettings | [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface) \| null | The [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface). | - -Returns: - -Promise<void> - -### Example - - -```javascript -const actionCodeSettings = { - url: 'https://www.example.com/?email=user@example.com', - iOS: { - bundleId: 'com.example.ios' - }, - android: { - packageName: 'com.example.android', - installApp: true, - minimumVersion: '12' - }, - handleCodeInApp: true -}; -await sendEmailVerification(user, actionCodeSettings); -// Obtain code from the user. -await applyActionCode(auth, code); - -``` - -## unlink() - -Unlinks a provider from a user account. - -Signature: - -```typescript -export declare function unlink(user: User, providerId: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| providerId | string | The provider to unlink. | - -Returns: - -Promise<[User](./auth.user.md#user_interface)> - -## updateEmail() - -Updates the user's email address. - -An email will be sent to the original email address (if it was set) that allows to revoke the email address change, in order to protect them from account hijacking. - -Important: this is a security sensitive operation that requires the user to have recently signed in. If this requirement isn't met, ask the user to authenticate again and then call [reauthenticateWithCredential()](./auth.md#reauthenticatewithcredential). - -Signature: - -```typescript -export declare function updateEmail(user: User, newEmail: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| newEmail | string | The new email address. | - -Returns: - -Promise<void> - -## updatePassword() - -Updates the user's password. - -Important: this is a security sensitive operation that requires the user to have recently signed in. If this requirement isn't met, ask the user to authenticate again and then call [reauthenticateWithCredential()](./auth.md#reauthenticatewithcredential). - -Signature: - -```typescript -export declare function updatePassword(user: User, newPassword: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| newPassword | string | The new password. | - -Returns: - -Promise<void> - -## updatePhoneNumber() - -Updates the user's phone number. - -Signature: - -```typescript -export declare function updatePhoneNumber(user: User, credential: PhoneAuthCredential): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| credential | [PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class) | A credential authenticating the new phone number. | - -Returns: - -Promise<void> - -### Example - - -``` -// 'recaptcha-container' is the ID of an element in the DOM. -const applicationVerifier = new RecaptchaVerifier('recaptcha-container'); -const provider = new PhoneAuthProvider(auth); -const verificationId = await provider.verifyPhoneNumber('+16505550101', applicationVerifier); -// Obtain the verificationCode from the user. -const phoneCredential = PhoneAuthProvider.credential(verificationId, verificationCode); -await updatePhoneNumber(user, phoneCredential); - -``` - -## updateProfile() - -Updates a user's profile data. - -Signature: - -```typescript -export declare function updateProfile(user: User, { displayName, photoURL: photoUrl }: { - displayName?: string | null; - photoURL?: string | null; -}): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| { displayName, photoURL: photoUrl } | { displayName?: string \| null; photoURL?: string \| null; } | | - -Returns: - -Promise<void> - -## verifyBeforeUpdateEmail() - -Sends a verification email to a new email address. - -The user's email will be updated to the new one after being verified. - -If you have a custom email action handler, you can complete the verification process by calling [applyActionCode()](./auth.md#applyactioncode). - -Signature: - -```typescript -export declare function verifyBeforeUpdateEmail(user: User, newEmail: string, actionCodeSettings?: ActionCodeSettings | null): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| user | [User](./auth.user.md#user_interface) | The user. | -| newEmail | string | The new email address to be verified before update. | -| actionCodeSettings | [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface) \| null | The [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface). | - -Returns: - -Promise<void> - -### Example - - -```javascript -const actionCodeSettings = { - url: 'https://www.example.com/?email=user@example.com', - iOS: { - bundleId: 'com.example.ios' - }, - android: { - packageName: 'com.example.android', - installApp: true, - minimumVersion: '12' - }, - handleCodeInApp: true -}; -await verifyBeforeUpdateEmail(user, 'newemail@example.com', actionCodeSettings); -// Obtain code from the user. -await applyActionCode(auth, code); - -``` - -## getAdditionalUserInfo() - -Extracts provider specific [AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface) for the given credential. - -Signature: - -```typescript -export declare function getAdditionalUserInfo(userCredential: UserCredential): AdditionalUserInfo | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | - -Returns: - -[AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface) \| null - -## ActionCodeOperation - -An enumeration of the possible email action types. - -Signature: - -```typescript -ActionCodeOperation: { - readonly EMAIL_SIGNIN: "EMAIL_SIGNIN"; - readonly PASSWORD_RESET: "PASSWORD_RESET"; - readonly RECOVER_EMAIL: "RECOVER_EMAIL"; - readonly REVERT_SECOND_FACTOR_ADDITION: "REVERT_SECOND_FACTOR_ADDITION"; - readonly VERIFY_AND_CHANGE_EMAIL: "VERIFY_AND_CHANGE_EMAIL"; - readonly VERIFY_EMAIL: "VERIFY_EMAIL"; -} -``` - -## AuthErrorCodes - -A map of potential `Auth` error codes, for easier comparison with errors thrown by the SDK. - -Note that you can't tree-shake individual keys in the map, so by using the map you might substantially increase your bundle size. - -Signature: - -```typescript -AUTH_ERROR_CODES_MAP_DO_NOT_USE_INTERNALLY: { - readonly ADMIN_ONLY_OPERATION: "auth/admin-restricted-operation"; - readonly ARGUMENT_ERROR: "auth/argument-error"; - readonly APP_NOT_AUTHORIZED: "auth/app-not-authorized"; - readonly APP_NOT_INSTALLED: "auth/app-not-installed"; - readonly CAPTCHA_CHECK_FAILED: "auth/captcha-check-failed"; - readonly CODE_EXPIRED: "auth/code-expired"; - readonly CORDOVA_NOT_READY: "auth/cordova-not-ready"; - readonly CORS_UNSUPPORTED: "auth/cors-unsupported"; - readonly CREDENTIAL_ALREADY_IN_USE: "auth/credential-already-in-use"; - readonly CREDENTIAL_MISMATCH: "auth/custom-token-mismatch"; - readonly CREDENTIAL_TOO_OLD_LOGIN_AGAIN: "auth/requires-recent-login"; - readonly DEPENDENT_SDK_INIT_BEFORE_AUTH: "auth/dependent-sdk-initialized-before-auth"; - readonly DYNAMIC_LINK_NOT_ACTIVATED: "auth/dynamic-link-not-activated"; - readonly EMAIL_CHANGE_NEEDS_VERIFICATION: "auth/email-change-needs-verification"; - readonly EMAIL_EXISTS: "auth/email-already-in-use"; - readonly EMULATOR_CONFIG_FAILED: "auth/emulator-config-failed"; - readonly EXPIRED_OOB_CODE: "auth/expired-action-code"; - readonly EXPIRED_POPUP_REQUEST: "auth/cancelled-popup-request"; - readonly INTERNAL_ERROR: "auth/internal-error"; - readonly INVALID_API_KEY: "auth/invalid-api-key"; - readonly INVALID_APP_CREDENTIAL: "auth/invalid-app-credential"; - readonly INVALID_APP_ID: "auth/invalid-app-id"; - readonly INVALID_AUTH: "auth/invalid-user-token"; - readonly INVALID_AUTH_EVENT: "auth/invalid-auth-event"; - readonly INVALID_CERT_HASH: "auth/invalid-cert-hash"; - readonly INVALID_CODE: "auth/invalid-verification-code"; - readonly INVALID_CONTINUE_URI: "auth/invalid-continue-uri"; - readonly INVALID_CORDOVA_CONFIGURATION: "auth/invalid-cordova-configuration"; - readonly INVALID_CUSTOM_TOKEN: "auth/invalid-custom-token"; - readonly INVALID_DYNAMIC_LINK_DOMAIN: "auth/invalid-dynamic-link-domain"; - readonly INVALID_EMAIL: "auth/invalid-email"; - readonly INVALID_EMULATOR_SCHEME: "auth/invalid-emulator-scheme"; - readonly INVALID_IDP_RESPONSE: "auth/invalid-credential"; - readonly INVALID_MESSAGE_PAYLOAD: "auth/invalid-message-payload"; - readonly INVALID_MFA_SESSION: "auth/invalid-multi-factor-session"; - readonly INVALID_OAUTH_CLIENT_ID: "auth/invalid-oauth-client-id"; - readonly INVALID_OAUTH_PROVIDER: "auth/invalid-oauth-provider"; - readonly INVALID_OOB_CODE: "auth/invalid-action-code"; - readonly INVALID_ORIGIN: "auth/unauthorized-domain"; - readonly INVALID_PASSWORD: "auth/wrong-password"; - readonly INVALID_PERSISTENCE: "auth/invalid-persistence-type"; - readonly INVALID_PHONE_NUMBER: "auth/invalid-phone-number"; - readonly INVALID_PROVIDER_ID: "auth/invalid-provider-id"; - readonly INVALID_RECIPIENT_EMAIL: "auth/invalid-recipient-email"; - readonly INVALID_SENDER: "auth/invalid-sender"; - readonly INVALID_SESSION_INFO: "auth/invalid-verification-id"; - readonly INVALID_TENANT_ID: "auth/invalid-tenant-id"; - readonly MFA_INFO_NOT_FOUND: "auth/multi-factor-info-not-found"; - readonly MFA_REQUIRED: "auth/multi-factor-auth-required"; - readonly MISSING_ANDROID_PACKAGE_NAME: "auth/missing-android-pkg-name"; - readonly MISSING_APP_CREDENTIAL: "auth/missing-app-credential"; - readonly MISSING_AUTH_DOMAIN: "auth/auth-domain-config-required"; - readonly MISSING_CODE: "auth/missing-verification-code"; - readonly MISSING_CONTINUE_URI: "auth/missing-continue-uri"; - readonly MISSING_IFRAME_START: "auth/missing-iframe-start"; - readonly MISSING_IOS_BUNDLE_ID: "auth/missing-ios-bundle-id"; - readonly MISSING_OR_INVALID_NONCE: "auth/missing-or-invalid-nonce"; - readonly MISSING_MFA_INFO: "auth/missing-multi-factor-info"; - readonly MISSING_MFA_SESSION: "auth/missing-multi-factor-session"; - readonly MISSING_PHONE_NUMBER: "auth/missing-phone-number"; - readonly MISSING_SESSION_INFO: "auth/missing-verification-id"; - readonly MODULE_DESTROYED: "auth/app-deleted"; - readonly NEED_CONFIRMATION: "auth/account-exists-with-different-credential"; - readonly NETWORK_REQUEST_FAILED: "auth/network-request-failed"; - readonly NULL_USER: "auth/null-user"; - readonly NO_AUTH_EVENT: "auth/no-auth-event"; - readonly NO_SUCH_PROVIDER: "auth/no-such-provider"; - readonly OPERATION_NOT_ALLOWED: "auth/operation-not-allowed"; - readonly OPERATION_NOT_SUPPORTED: "auth/operation-not-supported-in-this-environment"; - readonly POPUP_BLOCKED: "auth/popup-blocked"; - readonly POPUP_CLOSED_BY_USER: "auth/popup-closed-by-user"; - readonly PROVIDER_ALREADY_LINKED: "auth/provider-already-linked"; - readonly QUOTA_EXCEEDED: "auth/quota-exceeded"; - readonly REDIRECT_CANCELLED_BY_USER: "auth/redirect-cancelled-by-user"; - readonly REDIRECT_OPERATION_PENDING: "auth/redirect-operation-pending"; - readonly REJECTED_CREDENTIAL: "auth/rejected-credential"; - readonly SECOND_FACTOR_ALREADY_ENROLLED: "auth/second-factor-already-in-use"; - readonly SECOND_FACTOR_LIMIT_EXCEEDED: "auth/maximum-second-factor-count-exceeded"; - readonly TENANT_ID_MISMATCH: "auth/tenant-id-mismatch"; - readonly TIMEOUT: "auth/timeout"; - readonly TOKEN_EXPIRED: "auth/user-token-expired"; - readonly TOO_MANY_ATTEMPTS_TRY_LATER: "auth/too-many-requests"; - readonly UNAUTHORIZED_DOMAIN: "auth/unauthorized-continue-uri"; - readonly UNSUPPORTED_FIRST_FACTOR: "auth/unsupported-first-factor"; - readonly UNSUPPORTED_PERSISTENCE: "auth/unsupported-persistence-type"; - readonly UNSUPPORTED_TENANT_OPERATION: "auth/unsupported-tenant-operation"; - readonly UNVERIFIED_EMAIL: "auth/unverified-email"; - readonly USER_CANCELLED: "auth/user-cancelled"; - readonly USER_DELETED: "auth/user-not-found"; - readonly USER_DISABLED: "auth/user-disabled"; - readonly USER_MISMATCH: "auth/user-mismatch"; - readonly USER_SIGNED_OUT: "auth/user-signed-out"; - readonly WEAK_PASSWORD: "auth/weak-password"; - readonly WEB_STORAGE_UNSUPPORTED: "auth/web-storage-unsupported"; - readonly ALREADY_INITIALIZED: "auth/already-initialized"; -} -``` - -## browserLocalPersistence - -An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type `LOCAL` using `localStorage` for the underlying storage. - -Signature: - -```typescript -browserLocalPersistence: Persistence -``` - -## browserPopupRedirectResolver - -An implementation of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) suitable for browser based applications. - -Signature: - -```typescript -browserPopupRedirectResolver: PopupRedirectResolver -``` - -## browserSessionPersistence - -An implementation of [Persistence](./auth.persistence.md#persistence_interface) of `SESSION` using `sessionStorage` for the underlying storage. - -Signature: - -```typescript -browserSessionPersistence: Persistence -``` - -## cordovaPopupRedirectResolver - -An implementation of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) suitable for Cordova based applications. - -Signature: - -```typescript -cordovaPopupRedirectResolver: PopupRedirectResolver -``` - -## debugErrorMap - -A verbose error map with detailed descriptions for most error codes. - -See discussion at [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) - -Signature: - -```typescript -debugErrorMap: AuthErrorMap -``` - -## FactorId - -An enum of factors that may be used for multifactor authentication. - -Signature: - -```typescript -FactorId: { - readonly PHONE: "phone"; -} -``` - -## indexedDBLocalPersistence - -An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type `LOCAL` using `indexedDB` for the underlying storage. - -Signature: - -```typescript -indexedDBLocalPersistence: Persistence -``` - -## inMemoryPersistence - -An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type 'NONE'. - -Signature: - -```typescript -inMemoryPersistence: Persistence -``` - -## OperationType - -Enumeration of supported operation types. - -Signature: - -```typescript -OperationType: { - readonly LINK: "link"; - readonly REAUTHENTICATE: "reauthenticate"; - readonly SIGN_IN: "signIn"; -} -``` - -## prodErrorMap - -A minimal error map with all verbose error messages stripped. - -See discussion at [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) - -Signature: - -```typescript -prodErrorMap: AuthErrorMap -``` - -## ProviderId - -Enumeration of supported providers. - -Signature: - -```typescript -ProviderId: { - readonly FACEBOOK: "facebook.com"; - readonly GITHUB: "github.com"; - readonly GOOGLE: "google.com"; - readonly PASSWORD: "password"; - readonly PHONE: "phone"; - readonly TWITTER: "twitter.com"; -} -``` - -## reactNativeLocalPersistence - -An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type 'LOCAL' for use in React Native environments. - -Signature: - -```typescript -reactNativeLocalPersistence: Persistence -``` - -## SignInMethod - -Enumeration of supported sign-in methods. - -Signature: - -```typescript -SignInMethod: { - readonly EMAIL_LINK: "emailLink"; - readonly EMAIL_PASSWORD: "password"; - readonly FACEBOOK: "facebook.com"; - readonly GITHUB: "github.com"; - readonly GOOGLE: "google.com"; - readonly PHONE: "phone"; - readonly TWITTER: "twitter.com"; -} -``` - -## CustomParameters - -Map of OAuth Custom Parameters. - -Signature: - -```typescript -export declare type CustomParameters = Record; -``` - -## NextOrObserver - -Type definition for an event callback. - -Signature: - -```typescript -export declare type NextOrObserver = NextFn | Observer; -``` - -## PhoneInfoOptions - -The information required to verify the ownership of a phone number. - -The information that's required depends on whether you are doing single-factor sign-in, multi-factor enrollment or multi-factor sign-in. - -Signature: - -```typescript -export declare type PhoneInfoOptions = PhoneSingleFactorInfoOptions | PhoneMultiFactorEnrollInfoOptions | PhoneMultiFactorSignInInfoOptions; -``` - -## UserProfile - -User profile used in [AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface). - -Signature: - -```typescript -export declare type UserProfile = Record; -``` diff --git a/docs-devsite/auth.multifactorassertion.md b/docs-devsite/auth.multifactorassertion.md deleted file mode 100644 index d7937ec1f64..00000000000 --- a/docs-devsite/auth.multifactorassertion.md +++ /dev/null @@ -1,37 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# MultiFactorAssertion interface -The base class for asserting ownership of a second factor. - -This is used to facilitate enrollment of a second factor on an existing user or sign-in of a user who already verified the first factor. - -Signature: - -```typescript -export interface MultiFactorAssertion -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [factorId](./auth.multifactorassertion.md#multifactorassertionfactorid) | typeof [FactorIdMap](./auth.md#factorid)\[keyof typeof [FactorIdMap](./auth.md#factorid)\] | The identifier of the second factor. | - -## MultiFactorAssertion.factorId - -The identifier of the second factor. - -Signature: - -```typescript -readonly factorId: typeof FactorIdMap[keyof typeof FactorIdMap]; -``` diff --git a/docs-devsite/auth.multifactorerror.md b/docs-devsite/auth.multifactorerror.md deleted file mode 100644 index a13276f5a61..00000000000 --- a/docs-devsite/auth.multifactorerror.md +++ /dev/null @@ -1,67 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# MultiFactorError interface -The error thrown when the user needs to provide a second factor to sign in successfully. - -The error code for this error is `auth/multi-factor-auth-required`. - -Signature: - -```typescript -export interface MultiFactorError extends AuthError -``` -Extends: [AuthError](./auth.autherror.md#autherror_interface) - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [customData](./auth.multifactorerror.md#multifactorerrorcustomdata) | [AuthError](./auth.autherror.md#autherror_interface)\['customData'\] & { readonly operationType: typeof [OperationTypeMap](./auth.md#operationtype)\[keyof typeof [OperationTypeMap](./auth.md#operationtype)\]; } | Details about the MultiFactorError. | - -## MultiFactorError.customData - -Details about the MultiFactorError. - -Signature: - -```typescript -readonly customData: AuthError['customData'] & { - readonly operationType: typeof OperationTypeMap[keyof typeof OperationTypeMap]; - }; -``` - -### Example - - -```javascript -let resolver; -let multiFactorHints; - -signInWithEmailAndPassword(auth, email, password) - .then((result) => { - // User signed in. No 2nd factor challenge is needed. - }) - .catch((error) => { - if (error.code == 'auth/multi-factor-auth-required') { - resolver = getMultiFactorResolver(auth, error); - multiFactorHints = resolver.hints; - } else { - // Handle other errors. - } - }); - -// Obtain a multiFactorAssertion by verifying the second factor. - -const userCredential = await resolver.resolveSignIn(multiFactorAssertion); - -``` - diff --git a/docs-devsite/auth.multifactorinfo.md b/docs-devsite/auth.multifactorinfo.md deleted file mode 100644 index 80a56164b9a..00000000000 --- a/docs-devsite/auth.multifactorinfo.md +++ /dev/null @@ -1,68 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# MultiFactorInfo interface -A structure containing the information of a second factor entity. - -Signature: - -```typescript -export interface MultiFactorInfo -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [displayName](./auth.multifactorinfo.md#multifactorinfodisplayname) | string \| null | The user friendly name of the current second factor. | -| [enrollmentTime](./auth.multifactorinfo.md#multifactorinfoenrollmenttime) | string | The enrollment date of the second factor formatted as a UTC string. | -| [factorId](./auth.multifactorinfo.md#multifactorinfofactorid) | typeof [FactorIdMap](./auth.md#factorid)\[keyof typeof [FactorIdMap](./auth.md#factorid)\] | The identifier of the second factor. | -| [uid](./auth.multifactorinfo.md#multifactorinfouid) | string | The multi-factor enrollment ID. | - -## MultiFactorInfo.displayName - -The user friendly name of the current second factor. - -Signature: - -```typescript -readonly displayName?: string | null; -``` - -## MultiFactorInfo.enrollmentTime - -The enrollment date of the second factor formatted as a UTC string. - -Signature: - -```typescript -readonly enrollmentTime: string; -``` - -## MultiFactorInfo.factorId - -The identifier of the second factor. - -Signature: - -```typescript -readonly factorId: typeof FactorIdMap[keyof typeof FactorIdMap]; -``` - -## MultiFactorInfo.uid - -The multi-factor enrollment ID. - -Signature: - -```typescript -readonly uid: string; -``` diff --git a/docs-devsite/auth.multifactorresolver.md b/docs-devsite/auth.multifactorresolver.md deleted file mode 100644 index 9d6bc3ebcda..00000000000 --- a/docs-devsite/auth.multifactorresolver.md +++ /dev/null @@ -1,128 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# MultiFactorResolver interface -The class used to facilitate recovery from [MultiFactorError](./auth.multifactorerror.md#multifactorerror_interface) when a user needs to provide a second factor to sign in. - -Signature: - -```typescript -export interface MultiFactorResolver -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [hints](./auth.multifactorresolver.md#multifactorresolverhints) | [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface)\[\] | The list of hints for the second factors needed to complete the sign-in for the current session. | -| [session](./auth.multifactorresolver.md#multifactorresolversession) | [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) | The session identifier for the current sign-in flow, which can be used to complete the second factor sign-in. | - -## Methods - -| Method | Description | -| --- | --- | -| [resolveSignIn(assertion)](./auth.multifactorresolver.md#multifactorresolverresolvesignin) | A helper function to help users complete sign in with a second factor using an [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) confirming the user successfully completed the second factor challenge. | - -## MultiFactorResolver.hints - -The list of hints for the second factors needed to complete the sign-in for the current session. - -Signature: - -```typescript -readonly hints: MultiFactorInfo[]; -``` - -## MultiFactorResolver.session - -The session identifier for the current sign-in flow, which can be used to complete the second factor sign-in. - -Signature: - -```typescript -readonly session: MultiFactorSession; -``` - -## MultiFactorResolver.resolveSignIn() - -A helper function to help users complete sign in with a second factor using an [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) confirming the user successfully completed the second factor challenge. - -Signature: - -```typescript -resolveSignIn(assertion: MultiFactorAssertion): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| assertion | [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) | The multi-factor assertion to resolve sign-in with. | - -Returns: - -Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> - -The promise that resolves with the user credential object. - -### Example - - -```javascript -const phoneAuthCredential = PhoneAuthProvider.credential(verificationId, verificationCode); -const multiFactorAssertion = PhoneMultiFactorGenerator.assertion(phoneAuthCredential); -const userCredential = await resolver.resolveSignIn(multiFactorAssertion); - -``` - -### Example - - -```javascript -let resolver; -let multiFactorHints; - -signInWithEmailAndPassword(auth, email, password) - .then((result) => { - // User signed in. No 2nd factor challenge is needed. - }) - .catch((error) => { - if (error.code == 'auth/multi-factor-auth-required') { - resolver = getMultiFactorResolver(auth, error); - // Show UI to let user select second factor. - multiFactorHints = resolver.hints; - } else { - // Handle other errors. - } - }); - -// The enrolled second factors that can be used to complete -// sign-in are returned in the `MultiFactorResolver.hints` list. -// UI needs to be presented to allow the user to select a second factor -// from that list. - -const selectedHint = // ; selected from multiFactorHints -const phoneAuthProvider = new PhoneAuthProvider(auth); -const phoneInfoOptions = { - multiFactorHint: selectedHint, - session: resolver.session -}; -const verificationId = phoneAuthProvider.verifyPhoneNumber(phoneInfoOptions, appVerifier); -// Store `verificationId` and show UI to let user enter verification code. - -// UI to enter verification code and continue. -// Continue button click handler -const phoneAuthCredential = PhoneAuthProvider.credential(verificationId, verificationCode); -const multiFactorAssertion = PhoneMultiFactorGenerator.assertion(phoneAuthCredential); -const userCredential = await resolver.resolveSignIn(multiFactorAssertion); - -``` - diff --git a/docs-devsite/auth.multifactorsession.md b/docs-devsite/auth.multifactorsession.md deleted file mode 100644 index 9ad2d0a1682..00000000000 --- a/docs-devsite/auth.multifactorsession.md +++ /dev/null @@ -1,19 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# MultiFactorSession interface -An interface defining the multi-factor session object used for enrolling a second factor on a user or helping sign in an enrolled user with a second factor. - -Signature: - -```typescript -export interface MultiFactorSession -``` diff --git a/docs-devsite/auth.multifactoruser.md b/docs-devsite/auth.multifactoruser.md deleted file mode 100644 index 9f25e4174fc..00000000000 --- a/docs-devsite/auth.multifactoruser.md +++ /dev/null @@ -1,161 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# MultiFactorUser interface -An interface that defines the multi-factor related properties and operations pertaining to a [User](./auth.user.md#user_interface). - -Signature: - -```typescript -export interface MultiFactorUser -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [enrolledFactors](./auth.multifactoruser.md#multifactoruserenrolledfactors) | [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface)\[\] | Returns a list of the user's enrolled second factors. | - -## Methods - -| Method | Description | -| --- | --- | -| [enroll(assertion, displayName)](./auth.multifactoruser.md#multifactoruserenroll) | Enrolls a second factor as identified by the [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) for the user. | -| [getSession()](./auth.multifactoruser.md#multifactorusergetsession) | Returns the session identifier for a second factor enrollment operation. This is used to identify the user trying to enroll a second factor. | -| [unenroll(option)](./auth.multifactoruser.md#multifactoruserunenroll) | Unenrolls the specified second factor. | - -## MultiFactorUser.enrolledFactors - -Returns a list of the user's enrolled second factors. - -Signature: - -```typescript -readonly enrolledFactors: MultiFactorInfo[]; -``` - -## MultiFactorUser.enroll() - -Enrolls a second factor as identified by the [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) for the user. - -On resolution, the user tokens are updated to reflect the change in the JWT payload. Accepts an additional display name parameter used to identify the second factor to the end user. Recent re-authentication is required for this operation to succeed. On successful enrollment, existing Firebase sessions (refresh tokens) are revoked. When a new factor is enrolled, an email notification is sent to the user’s email. - -Signature: - -```typescript -enroll(assertion: MultiFactorAssertion, displayName?: string | null): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| assertion | [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) | The multi-factor assertion to enroll with. | -| displayName | string \| null | The display name of the second factor. | - -Returns: - -Promise<void> - -### Example - - -```javascript -const multiFactorUser = multiFactor(auth.currentUser); -const multiFactorSession = await multiFactorUser.getSession(); - -// Send verification code. -const phoneAuthProvider = new PhoneAuthProvider(auth); -const phoneInfoOptions = { - phoneNumber: phoneNumber, - session: multiFactorSession -}; -const verificationId = await phoneAuthProvider.verifyPhoneNumber(phoneInfoOptions, appVerifier); - -// Obtain verification code from user. -const phoneAuthCredential = PhoneAuthProvider.credential(verificationId, verificationCode); -const multiFactorAssertion = PhoneMultiFactorGenerator.assertion(phoneAuthCredential); -await multiFactorUser.enroll(multiFactorAssertion); -// Second factor enrolled. - -``` - -## MultiFactorUser.getSession() - -Returns the session identifier for a second factor enrollment operation. This is used to identify the user trying to enroll a second factor. - -Signature: - -```typescript -getSession(): Promise; -``` -Returns: - -Promise<[MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface)> - -The promise that resolves with the [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface). - -### Example - - -```javascript -const multiFactorUser = multiFactor(auth.currentUser); -const multiFactorSession = await multiFactorUser.getSession(); - -// Send verification code. -const phoneAuthProvider = new PhoneAuthProvider(auth); -const phoneInfoOptions = { - phoneNumber: phoneNumber, - session: multiFactorSession -}; -const verificationId = await phoneAuthProvider.verifyPhoneNumber(phoneInfoOptions, appVerifier); - -// Obtain verification code from user. -const phoneAuthCredential = PhoneAuthProvider.credential(verificationId, verificationCode); -const multiFactorAssertion = PhoneMultiFactorGenerator.assertion(phoneAuthCredential); -await multiFactorUser.enroll(multiFactorAssertion); - -``` - -## MultiFactorUser.unenroll() - -Unenrolls the specified second factor. - -To specify the factor to remove, pass a [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) object (retrieved from [MultiFactorUser.enrolledFactors](./auth.multifactoruser.md#multifactoruserenrolledfactors)) or the factor's UID string. Sessions are not revoked when the account is unenrolled. An email notification is likely to be sent to the user notifying them of the change. Recent re-authentication is required for this operation to succeed. When an existing factor is unenrolled, an email notification is sent to the user’s email. - -Signature: - -```typescript -unenroll(option: MultiFactorInfo | string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| option | [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) \| string | The multi-factor option to unenroll. | - -Returns: - -Promise<void> - -- A `Promise` which resolves when the unenroll operation is complete. - -### Example - - -```javascript -const multiFactorUser = multiFactor(auth.currentUser); -// Present user the option to choose which factor to unenroll. -await multiFactorUser.unenroll(multiFactorUser.enrolledFactors[i]) - -``` - diff --git a/docs-devsite/auth.oauthcredential.md b/docs-devsite/auth.oauthcredential.md deleted file mode 100644 index dc3855e01a1..00000000000 --- a/docs-devsite/auth.oauthcredential.md +++ /dev/null @@ -1,105 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# OAuthCredential class -Represents the OAuth credentials returned by an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). - -Implementations specify the details about each auth provider's credential requirements. - -Signature: - -```typescript -export declare class OAuthCredential extends AuthCredential -``` -Extends: [AuthCredential](./auth.authcredential.md#authcredential_class) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [accessToken](./auth.oauthcredential.md#oauthcredentialaccesstoken) | | string | The OAuth access token associated with the credential if it belongs to an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class), such as facebook.com, twitter.com, etc. | -| [idToken](./auth.oauthcredential.md#oauthcredentialidtoken) | | string | The OAuth ID token associated with the credential if it belongs to an OIDC provider, such as google.com. | -| [secret](./auth.oauthcredential.md#oauthcredentialsecret) | | string | The OAuth access token secret associated with the credential if it belongs to an OAuth 1.0 provider, such as twitter.com. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [fromJSON(json)](./auth.oauthcredential.md#oauthcredentialfromjson) | static | Static method to deserialize a JSON representation of an object into an [AuthCredential](./auth.authcredential.md#authcredential_class). | -| [toJSON()](./auth.oauthcredential.md#oauthcredentialtojson) | | Returns a JSON-serializable representation of this object. | - -## OAuthCredential.accessToken - -The OAuth access token associated with the credential if it belongs to an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class), such as `facebook.com`, `twitter.com`, etc. - -Signature: - -```typescript -accessToken?: string; -``` - -## OAuthCredential.idToken - -The OAuth ID token associated with the credential if it belongs to an OIDC provider, such as `google.com`. - -Signature: - -```typescript -idToken?: string; -``` - -## OAuthCredential.secret - -The OAuth access token secret associated with the credential if it belongs to an OAuth 1.0 provider, such as `twitter.com`. - -Signature: - -```typescript -secret?: string; -``` - -## OAuthCredential.fromJSON() - -Static method to deserialize a JSON representation of an object into an [AuthCredential](./auth.authcredential.md#authcredential_class). - -Signature: - -```typescript -static fromJSON(json: string | object): OAuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| json | string \| object | Input can be either Object or the stringified representation of the object. When string is provided, JSON.parse would be called first. | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null - -If the JSON input does not represent an [AuthCredential](./auth.authcredential.md#authcredential_class), null is returned. - -## OAuthCredential.toJSON() - -Returns a JSON-serializable representation of this object. - -Signature: - -```typescript -toJSON(): object; -``` -Returns: - -object - -a JSON-serializable representation of this object. - diff --git a/docs-devsite/auth.oauthcredentialoptions.md b/docs-devsite/auth.oauthcredentialoptions.md deleted file mode 100644 index 0389c534c17..00000000000 --- a/docs-devsite/auth.oauthcredentialoptions.md +++ /dev/null @@ -1,61 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# OAuthCredentialOptions interface -Defines the options for initializing an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). - -For ID tokens with nonce claim, the raw nonce has to also be provided. - -Signature: - -```typescript -export interface OAuthCredentialOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [accessToken](./auth.oauthcredentialoptions.md#oauthcredentialoptionsaccesstoken) | string | The OAuth access token used to initialize the [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). | -| [idToken](./auth.oauthcredentialoptions.md#oauthcredentialoptionsidtoken) | string | The OAuth ID token used to initialize the [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). | -| [rawNonce](./auth.oauthcredentialoptions.md#oauthcredentialoptionsrawnonce) | string | The raw nonce associated with the ID token. | - -## OAuthCredentialOptions.accessToken - -The OAuth access token used to initialize the [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). - -Signature: - -```typescript -accessToken?: string; -``` - -## OAuthCredentialOptions.idToken - -The OAuth ID token used to initialize the [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). - -Signature: - -```typescript -idToken?: string; -``` - -## OAuthCredentialOptions.rawNonce - -The raw nonce associated with the ID token. - -It is required when an ID token with a nonce field is provided. The SHA-256 hash of the raw nonce must match the nonce field in the ID token. - -Signature: - -```typescript -rawNonce?: string; -``` diff --git a/docs-devsite/auth.oauthprovider.md b/docs-devsite/auth.oauthprovider.md deleted file mode 100644 index 30141fcce40..00000000000 --- a/docs-devsite/auth.oauthprovider.md +++ /dev/null @@ -1,168 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# OAuthProvider class -Provider for generating generic [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). - -Signature: - -```typescript -export declare class OAuthProvider extends BaseOAuthProvider -``` -Extends: BaseOAuthProvider - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [credential(params)](./auth.oauthprovider.md#oauthprovidercredential) | | Creates a [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a generic OAuth provider's access token or ID token. | -| [credentialFromError(error)](./auth.oauthprovider.md#oauthprovidercredentialfromerror) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. | -| [credentialFromJSON(json)](./auth.oauthprovider.md#oauthprovidercredentialfromjson) | static | Creates an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a JSON string or a plain object. | -| [credentialFromResult(userCredential)](./auth.oauthprovider.md#oauthprovidercredentialfromresult) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). | - -## OAuthProvider.credential() - -Creates a [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a generic OAuth provider's access token or ID token. - -The raw nonce is required when an ID token with a nonce field is provided. The SHA-256 hash of the raw nonce must match the nonce field in the ID token. - -Signature: - -```typescript -credential(params: OAuthCredentialOptions): OAuthCredential; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| params | [OAuthCredentialOptions](./auth.oauthcredentialoptions.md#oauthcredentialoptions_interface) | Either the options object containing the ID token, access token and raw nonce or the ID token string. | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) - -### Example - - -```javascript -// `googleUser` from the onsuccess Google Sign In callback. -// Initialize a generate OAuth provider with a `google.com` providerId. -const provider = new OAuthProvider('google.com'); -const credential = provider.credential({ - idToken: googleUser.getAuthResponse().id_token, -}); -const result = await signInWithCredential(credential); - -``` - -## OAuthProvider.credentialFromError() - -Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. - -Signature: - -```typescript -static credentialFromError(error: FirebaseError): OAuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null - -## OAuthProvider.credentialFromJSON() - -Creates an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a JSON string or a plain object. - -Signature: - -```typescript -static credentialFromJSON(json: object | string): OAuthCredential; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| json | object \| string | A plain object or a JSON string | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) - -## OAuthProvider.credentialFromResult() - -Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). - -Signature: - -```typescript -static credentialFromResult(userCredential: UserCredential): OAuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null - -### Example 1 - - -```javascript -// Sign in using a redirect. -const provider = new OAuthProvider('google.com'); -// Start a sign in process for an unauthenticated user. -provider.addScope('profile'); -provider.addScope('email'); -await signInWithRedirect(auth, provider); -// This will trigger a full page redirect away from your app - -// After returning from the redirect when your app initializes you can obtain the result -const result = await getRedirectResult(auth); -if (result) { - // This is the signed-in user - const user = result.user; - // This gives you a OAuth Access Token for the provider. - const credential = provider.credentialFromResult(auth, result); - const token = credential.accessToken; -} - -``` - -### Example 2 - - -```javascript -// Sign in using a popup. -const provider = new OAuthProvider('google.com'); -provider.addScope('profile'); -provider.addScope('email'); -const result = await signInWithPopup(auth, provider); - -// The signed-in user info. -const user = result.user; -// This gives you a OAuth Access Token for the provider. -const credential = provider.credentialFromResult(auth, result); -const token = credential.accessToken; - -``` - diff --git a/docs-devsite/auth.parsedtoken.md b/docs-devsite/auth.parsedtoken.md deleted file mode 100644 index 7892b135536..00000000000 --- a/docs-devsite/auth.parsedtoken.md +++ /dev/null @@ -1,83 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ParsedToken interface -Interface representing a parsed ID token. - -Signature: - -```typescript -export interface ParsedToken -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [auth\_time](./auth.parsedtoken.md#parsedtokenauth_time) | string | Time at which authentication was performed. | -| [exp](./auth.parsedtoken.md#parsedtokenexp) | string | Expiration time of the token. | -| [firebase](./auth.parsedtoken.md#parsedtokenfirebase) | { 'sign\_in\_provider'?: string; 'sign\_in\_second\_factor'?: string; 'identities'?: Record<string, string>; } | Firebase specific claims, containing the provider(s) used to authenticate the user. | -| [iat](./auth.parsedtoken.md#parsedtokeniat) | string | Issuance time of the token. | -| [sub](./auth.parsedtoken.md#parsedtokensub) | string | UID of the user. | - -## ParsedToken.auth\_time - -Time at which authentication was performed. - -Signature: - -```typescript -'auth_time'?: string; -``` - -## ParsedToken.exp - -Expiration time of the token. - -Signature: - -```typescript -'exp'?: string; -``` - -## ParsedToken.firebase - -Firebase specific claims, containing the provider(s) used to authenticate the user. - -Signature: - -```typescript -'firebase'?: { - 'sign_in_provider'?: string; - 'sign_in_second_factor'?: string; - 'identities'?: Record; - }; -``` - -## ParsedToken.iat - -Issuance time of the token. - -Signature: - -```typescript -'iat'?: string; -``` - -## ParsedToken.sub - -UID of the user. - -Signature: - -```typescript -'sub'?: string; -``` diff --git a/docs-devsite/auth.persistence.md b/docs-devsite/auth.persistence.md deleted file mode 100644 index b3f9ecb11e1..00000000000 --- a/docs-devsite/auth.persistence.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Persistence interface -An interface covering the possible persistence mechanism types. - -Signature: - -```typescript -export interface Persistence -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [type](./auth.persistence.md#persistencetype) | 'SESSION' \| 'LOCAL' \| 'NONE' | Type of Persistence. - 'SESSION' is used for temporary persistence such as sessionStorage. - 'LOCAL' is used for long term persistence such as localStorage or IndexedDB. - 'NONE' is used for in-memory, or no persistence. | - -## Persistence.type - -Type of Persistence. - 'SESSION' is used for temporary persistence such as `sessionStorage`. - 'LOCAL' is used for long term persistence such as `localStorage` or `IndexedDB`. - 'NONE' is used for in-memory, or no persistence. - -Signature: - -```typescript -readonly type: 'SESSION' | 'LOCAL' | 'NONE'; -``` diff --git a/docs-devsite/auth.phoneauthcredential.md b/docs-devsite/auth.phoneauthcredential.md deleted file mode 100644 index 44a85db5254..00000000000 --- a/docs-devsite/auth.phoneauthcredential.md +++ /dev/null @@ -1,63 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# PhoneAuthCredential class -Represents the credentials returned by [PhoneAuthProvider](./auth.phoneauthprovider.md#phoneauthprovider_class). - -Signature: - -```typescript -export declare class PhoneAuthCredential extends AuthCredential -``` -Extends: [AuthCredential](./auth.authcredential.md#authcredential_class) - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [fromJSON(json)](./auth.phoneauthcredential.md#phoneauthcredentialfromjson) | static | Generates a phone credential based on a plain object or a JSON string. | -| [toJSON()](./auth.phoneauthcredential.md#phoneauthcredentialtojson) | | Returns a JSON-serializable representation of this object. | - -## PhoneAuthCredential.fromJSON() - -Generates a phone credential based on a plain object or a JSON string. - -Signature: - -```typescript -static fromJSON(json: object | string): PhoneAuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| json | object \| string | | - -Returns: - -[PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class) \| null - -## PhoneAuthCredential.toJSON() - -Returns a JSON-serializable representation of this object. - -Signature: - -```typescript -toJSON(): object; -``` -Returns: - -object - -a JSON-serializable representation of this object. - diff --git a/docs-devsite/auth.phoneauthprovider.md b/docs-devsite/auth.phoneauthprovider.md deleted file mode 100644 index 41e743386de..00000000000 --- a/docs-devsite/auth.phoneauthprovider.md +++ /dev/null @@ -1,256 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# PhoneAuthProvider class -Provider for generating an [PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class). - -Signature: - -```typescript -export declare class PhoneAuthProvider -``` - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(auth)](./auth.phoneauthprovider.md#phoneauthproviderconstructor) | | Constructs a new instance of the PhoneAuthProvider class | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [PHONE\_SIGN\_IN\_METHOD](./auth.phoneauthprovider.md#phoneauthproviderphone_sign_in_method) | static | 'phone' | Always set to [SignInMethod](./auth.md#signinmethod).PHONE. | -| [PROVIDER\_ID](./auth.phoneauthprovider.md#phoneauthproviderprovider_id) | static | 'phone' | Always set to [ProviderId](./auth.md#providerid).PHONE. | -| [providerId](./auth.phoneauthprovider.md#phoneauthproviderproviderid) | | "phone" | Always set to [ProviderId](./auth.md#providerid).PHONE. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [credential(verificationId, verificationCode)](./auth.phoneauthprovider.md#phoneauthprovidercredential) | static | Creates a phone auth credential, given the verification ID from [PhoneAuthProvider.verifyPhoneNumber()](./auth.phoneauthprovider.md#phoneauthproviderverifyphonenumber) and the code that was sent to the user's mobile device. | -| [credentialFromError(error)](./auth.phoneauthprovider.md#phoneauthprovidercredentialfromerror) | static | Returns an [AuthCredential](./auth.authcredential.md#authcredential_class) when passed an error. | -| [credentialFromResult(userCredential)](./auth.phoneauthprovider.md#phoneauthprovidercredentialfromresult) | static | Generates an [AuthCredential](./auth.authcredential.md#authcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). | -| [verifyPhoneNumber(phoneOptions, applicationVerifier)](./auth.phoneauthprovider.md#phoneauthproviderverifyphonenumber) | | Starts a phone number authentication flow by sending a verification code to the given phone number. | - -## PhoneAuthProvider.(constructor) - -Constructs a new instance of the `PhoneAuthProvider` class - -Signature: - -```typescript -constructor(auth: Auth); -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| auth | [Auth](./auth.auth.md#auth_interface) | The Firebase [Auth](./auth.auth.md#auth_interface) instance in which sign-ins should occur. | - -## PhoneAuthProvider.PHONE\_SIGN\_IN\_METHOD - -Always set to [SignInMethod](./auth.md#signinmethod).PHONE. - -Signature: - -```typescript -static readonly PHONE_SIGN_IN_METHOD: 'phone'; -``` - -## PhoneAuthProvider.PROVIDER\_ID - -Always set to [ProviderId](./auth.md#providerid).PHONE. - -Signature: - -```typescript -static readonly PROVIDER_ID: 'phone'; -``` - -## PhoneAuthProvider.providerId - -Always set to [ProviderId](./auth.md#providerid).PHONE. - -Signature: - -```typescript -readonly providerId: "phone"; -``` - -## PhoneAuthProvider.credential() - -Creates a phone auth credential, given the verification ID from [PhoneAuthProvider.verifyPhoneNumber()](./auth.phoneauthprovider.md#phoneauthproviderverifyphonenumber) and the code that was sent to the user's mobile device. - -Signature: - -```typescript -static credential(verificationId: string, verificationCode: string): PhoneAuthCredential; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| verificationId | string | The verification ID returned from [PhoneAuthProvider.verifyPhoneNumber()](./auth.phoneauthprovider.md#phoneauthproviderverifyphonenumber). | -| verificationCode | string | The verification code sent to the user's mobile device. | - -Returns: - -[PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class) - -The auth provider credential. - -### Example 1 - - -```javascript -const provider = new PhoneAuthProvider(auth); -const verificationId = provider.verifyPhoneNumber(phoneNumber, applicationVerifier); -// Obtain verificationCode from the user. -const authCredential = PhoneAuthProvider.credential(verificationId, verificationCode); -const userCredential = signInWithCredential(auth, authCredential); - -``` - -### Example 2 - -An alternative flow is provided using the `signInWithPhoneNumber` method. - -```javascript -const confirmationResult = await signInWithPhoneNumber(auth, phoneNumber, applicationVerifier); -// Obtain verificationCode from the user. -const userCredential = await confirmationResult.confirm(verificationCode); - -``` - -## PhoneAuthProvider.credentialFromError() - -Returns an [AuthCredential](./auth.authcredential.md#authcredential_class) when passed an error. - -This method works for errors like `auth/account-exists-with-different-credentials`. This is useful for recovering when attempting to set a user's phone number but the number in question is already tied to another account. For example, the following code tries to update the current user's phone number, and if that fails, links the user with the account associated with that number: - -```js -const provider = new PhoneAuthProvider(auth); -const verificationId = await provider.verifyPhoneNumber(number, verifier); -try { - const code = ''; // Prompt the user for the verification code - await updatePhoneNumber( - auth.currentUser, - PhoneAuthProvider.credential(verificationId, code)); -} catch (e) { - if ((e as FirebaseError)?.code === 'auth/account-exists-with-different-credential') { - const cred = PhoneAuthProvider.credentialFromError(e); - await linkWithCredential(auth.currentUser, cred); - } -} - -// At this point, auth.currentUser.phoneNumber === number. - -``` - -Signature: - -```typescript -static credentialFromError(error: FirebaseError): AuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | The error to generate a credential from. | - -Returns: - -[AuthCredential](./auth.authcredential.md#authcredential_class) \| null - -## PhoneAuthProvider.credentialFromResult() - -Generates an [AuthCredential](./auth.authcredential.md#authcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). - -Signature: - -```typescript -static credentialFromResult(userCredential: UserCredential): AuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | - -Returns: - -[AuthCredential](./auth.authcredential.md#authcredential_class) \| null - -## PhoneAuthProvider.verifyPhoneNumber() - -Starts a phone number authentication flow by sending a verification code to the given phone number. - -Signature: - -```typescript -verifyPhoneNumber(phoneOptions: PhoneInfoOptions | string, applicationVerifier: ApplicationVerifier): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| phoneOptions | [PhoneInfoOptions](./auth.md#phoneinfooptions) \| string | | -| applicationVerifier | [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) | For abuse prevention, this method also requires a [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface). This SDK includes a reCAPTCHA-based implementation, [RecaptchaVerifier](./auth.recaptchaverifier.md#recaptchaverifier_class). | - -Returns: - -Promise<string> - -A Promise for a verification ID that can be passed to [PhoneAuthProvider.credential()](./auth.phoneauthprovider.md#phoneauthprovidercredential) to identify this flow.. - -### Example 1 - - -```javascript -const provider = new PhoneAuthProvider(auth); -const verificationId = await provider.verifyPhoneNumber(phoneNumber, applicationVerifier); -// Obtain verificationCode from the user. -const authCredential = PhoneAuthProvider.credential(verificationId, verificationCode); -const userCredential = await signInWithCredential(auth, authCredential); - -``` - -### Example 2 - -An alternative flow is provided using the `signInWithPhoneNumber` method. - -```javascript -const confirmationResult = signInWithPhoneNumber(auth, phoneNumber, applicationVerifier); -// Obtain verificationCode from the user. -const userCredential = confirmationResult.confirm(verificationCode); - -``` - -### Example - - -```javascript -// 'recaptcha-container' is the ID of an element in the DOM. -const applicationVerifier = new RecaptchaVerifier('recaptcha-container'); -const provider = new PhoneAuthProvider(auth); -const verificationId = await provider.verifyPhoneNumber('+16505550101', applicationVerifier); -// Obtain the verificationCode from the user. -const phoneCredential = PhoneAuthProvider.credential(verificationId, verificationCode); -const userCredential = await signInWithCredential(auth, phoneCredential); - -``` - diff --git a/docs-devsite/auth.phonemultifactorassertion.md b/docs-devsite/auth.phonemultifactorassertion.md deleted file mode 100644 index 1f6afd2410f..00000000000 --- a/docs-devsite/auth.phonemultifactorassertion.md +++ /dev/null @@ -1,21 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# PhoneMultiFactorAssertion interface -The class for asserting ownership of a phone second factor. Provided by [PhoneMultiFactorGenerator.assertion()](./auth.phonemultifactorgenerator.md#phonemultifactorgeneratorassertion). - -Signature: - -```typescript -export interface PhoneMultiFactorAssertion extends MultiFactorAssertion -``` -Extends: [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) - diff --git a/docs-devsite/auth.phonemultifactorenrollinfooptions.md b/docs-devsite/auth.phonemultifactorenrollinfooptions.md deleted file mode 100644 index f36cfc29d8d..00000000000 --- a/docs-devsite/auth.phonemultifactorenrollinfooptions.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# PhoneMultiFactorEnrollInfoOptions interface -Options used for enrolling a second factor. - -Signature: - -```typescript -export interface PhoneMultiFactorEnrollInfoOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [phoneNumber](./auth.phonemultifactorenrollinfooptions.md#phonemultifactorenrollinfooptionsphonenumber) | string | Phone number to send a verification code to. | -| [session](./auth.phonemultifactorenrollinfooptions.md#phonemultifactorenrollinfooptionssession) | [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) | The [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) obtained via [MultiFactorUser.getSession()](./auth.multifactoruser.md#multifactorusergetsession). | - -## PhoneMultiFactorEnrollInfoOptions.phoneNumber - -Phone number to send a verification code to. - -Signature: - -```typescript -phoneNumber: string; -``` - -## PhoneMultiFactorEnrollInfoOptions.session - -The [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) obtained via [MultiFactorUser.getSession()](./auth.multifactoruser.md#multifactorusergetsession). - -Signature: - -```typescript -session: MultiFactorSession; -``` diff --git a/docs-devsite/auth.phonemultifactorgenerator.md b/docs-devsite/auth.phonemultifactorgenerator.md deleted file mode 100644 index a59d34814bf..00000000000 --- a/docs-devsite/auth.phonemultifactorgenerator.md +++ /dev/null @@ -1,64 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# PhoneMultiFactorGenerator class -Provider for generating a [PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface). - -Signature: - -```typescript -export declare class PhoneMultiFactorGenerator -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [FACTOR\_ID](./auth.phonemultifactorgenerator.md#phonemultifactorgeneratorfactor_id) | static | string | The identifier of the phone second factor: phone. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [assertion(credential)](./auth.phonemultifactorgenerator.md#phonemultifactorgeneratorassertion) | static | Provides a [PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface) to confirm ownership of the phone second factor. | - -## PhoneMultiFactorGenerator.FACTOR\_ID - -The identifier of the phone second factor: `phone`. - -Signature: - -```typescript -static FACTOR_ID: string; -``` - -## PhoneMultiFactorGenerator.assertion() - -Provides a [PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface) to confirm ownership of the phone second factor. - -Signature: - -```typescript -static assertion(credential: PhoneAuthCredential): PhoneMultiFactorAssertion; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| credential | [PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class) | | - -Returns: - -[PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface) - -A [PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface) which can be used with [MultiFactorResolver.resolveSignIn()](./auth.multifactorresolver.md#multifactorresolverresolvesignin) - diff --git a/docs-devsite/auth.phonemultifactorinfo.md b/docs-devsite/auth.phonemultifactorinfo.md deleted file mode 100644 index c12c72b8a55..00000000000 --- a/docs-devsite/auth.phonemultifactorinfo.md +++ /dev/null @@ -1,36 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# PhoneMultiFactorInfo interface -The subclass of the [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) interface for phone number second factors. The `factorId` of this second factor is [FactorId](./auth.md#factorid).PHONE. - -Signature: - -```typescript -export interface PhoneMultiFactorInfo extends MultiFactorInfo -``` -Extends: [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [phoneNumber](./auth.phonemultifactorinfo.md#phonemultifactorinfophonenumber) | string | The phone number associated with the current second factor. | - -## PhoneMultiFactorInfo.phoneNumber - -The phone number associated with the current second factor. - -Signature: - -```typescript -readonly phoneNumber: string; -``` diff --git a/docs-devsite/auth.phonemultifactorsignininfooptions.md b/docs-devsite/auth.phonemultifactorsignininfooptions.md deleted file mode 100644 index 592ef7118b3..00000000000 --- a/docs-devsite/auth.phonemultifactorsignininfooptions.md +++ /dev/null @@ -1,61 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# PhoneMultiFactorSignInInfoOptions interface -Options used for signing in with a second factor. - -Signature: - -```typescript -export interface PhoneMultiFactorSignInInfoOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [multiFactorHint](./auth.phonemultifactorsignininfooptions.md#phonemultifactorsignininfooptionsmultifactorhint) | [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) | The [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) obtained via [MultiFactorResolver.hints](./auth.multifactorresolver.md#multifactorresolverhints).One of multiFactorHint or multiFactorUid is required. | -| [multiFactorUid](./auth.phonemultifactorsignininfooptions.md#phonemultifactorsignininfooptionsmultifactoruid) | string | The uid of the second factor.One of multiFactorHint or multiFactorUid is required. | -| [session](./auth.phonemultifactorsignininfooptions.md#phonemultifactorsignininfooptionssession) | [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) | The [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) obtained via [MultiFactorResolver.session](./auth.multifactorresolver.md#multifactorresolversession). | - -## PhoneMultiFactorSignInInfoOptions.multiFactorHint - -The [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) obtained via [MultiFactorResolver.hints](./auth.multifactorresolver.md#multifactorresolverhints). - -One of `multiFactorHint` or `multiFactorUid` is required. - -Signature: - -```typescript -multiFactorHint?: MultiFactorInfo; -``` - -## PhoneMultiFactorSignInInfoOptions.multiFactorUid - -The uid of the second factor. - -One of `multiFactorHint` or `multiFactorUid` is required. - -Signature: - -```typescript -multiFactorUid?: string; -``` - -## PhoneMultiFactorSignInInfoOptions.session - -The [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) obtained via [MultiFactorResolver.session](./auth.multifactorresolver.md#multifactorresolversession). - -Signature: - -```typescript -session: MultiFactorSession; -``` diff --git a/docs-devsite/auth.phonesinglefactorinfooptions.md b/docs-devsite/auth.phonesinglefactorinfooptions.md deleted file mode 100644 index f7846d0db42..00000000000 --- a/docs-devsite/auth.phonesinglefactorinfooptions.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# PhoneSingleFactorInfoOptions interface -Options used for single-factor sign-in. - -Signature: - -```typescript -export interface PhoneSingleFactorInfoOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [phoneNumber](./auth.phonesinglefactorinfooptions.md#phonesinglefactorinfooptionsphonenumber) | string | Phone number to send a verification code to. | - -## PhoneSingleFactorInfoOptions.phoneNumber - -Phone number to send a verification code to. - -Signature: - -```typescript -phoneNumber: string; -``` diff --git a/docs-devsite/auth.popupredirectresolver.md b/docs-devsite/auth.popupredirectresolver.md deleted file mode 100644 index 67c3274847c..00000000000 --- a/docs-devsite/auth.popupredirectresolver.md +++ /dev/null @@ -1,19 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# PopupRedirectResolver interface -A resolver used for handling DOM specific operations like [signInWithPopup()](./auth.md#signinwithpopup) or [signInWithRedirect()](./auth.md#signinwithredirect). - -Signature: - -```typescript -export interface PopupRedirectResolver -``` diff --git a/docs-devsite/auth.reactnativeasyncstorage.md b/docs-devsite/auth.reactnativeasyncstorage.md deleted file mode 100644 index 231e7d2ed31..00000000000 --- a/docs-devsite/auth.reactnativeasyncstorage.md +++ /dev/null @@ -1,89 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ReactNativeAsyncStorage interface -Interface for a supplied `AsyncStorage`. - -Signature: - -```typescript -export interface ReactNativeAsyncStorage -``` - -## Methods - -| Method | Description | -| --- | --- | -| [getItem(key)](./auth.reactnativeasyncstorage.md#reactnativeasyncstoragegetitem) | Retrieve an item from storage. | -| [removeItem(key)](./auth.reactnativeasyncstorage.md#reactnativeasyncstorageremoveitem) | Remove an item from storage. | -| [setItem(key, value)](./auth.reactnativeasyncstorage.md#reactnativeasyncstoragesetitem) | Persist an item in storage. | - -## ReactNativeAsyncStorage.getItem() - -Retrieve an item from storage. - -Signature: - -```typescript -getItem(key: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| key | string | storage key. | - -Returns: - -Promise<string \| null> - -## ReactNativeAsyncStorage.removeItem() - -Remove an item from storage. - -Signature: - -```typescript -removeItem(key: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| key | string | storage key. | - -Returns: - -Promise<void> - -## ReactNativeAsyncStorage.setItem() - -Persist an item in storage. - -Signature: - -```typescript -setItem(key: string, value: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| key | string | storage key. | -| value | string | storage value. | - -Returns: - -Promise<void> - diff --git a/docs-devsite/auth.recaptchaparameters.md b/docs-devsite/auth.recaptchaparameters.md deleted file mode 100644 index 5d70f1826eb..00000000000 --- a/docs-devsite/auth.recaptchaparameters.md +++ /dev/null @@ -1,23 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# RecaptchaParameters interface -Interface representing reCAPTCHA parameters. - -See the \[reCAPTCHA docs\](https://developers.google.com/recaptcha/docs/display\#render\_param) for the list of accepted parameters. All parameters are accepted except for `sitekey`: Firebase Auth provisions a reCAPTCHA for each project and will configure the site key upon rendering. - -For an invisible reCAPTCHA, set the `size` key to `invisible`. - -Signature: - -```typescript -export interface RecaptchaParameters -``` diff --git a/docs-devsite/auth.recaptchaverifier.md b/docs-devsite/auth.recaptchaverifier.md deleted file mode 100644 index 4f32d489aed..00000000000 --- a/docs-devsite/auth.recaptchaverifier.md +++ /dev/null @@ -1,116 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# RecaptchaVerifier class -An [reCAPTCHA](https://www.google.com/recaptcha/)-based application verifier. - -Signature: - -```typescript -export declare class RecaptchaVerifier implements ApplicationVerifierInternal -``` -Implements: ApplicationVerifierInternal - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(containerOrId, parameters, authExtern)](./auth.recaptchaverifier.md#recaptchaverifierconstructor) | | Constructs a new instance of the RecaptchaVerifier class | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./auth.recaptchaverifier.md#recaptchaverifiertype) | | (not declared) | The application verifier type. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [clear()](./auth.recaptchaverifier.md#recaptchaverifierclear) | | Clears the reCAPTCHA widget from the page and destroys the instance. | -| [render()](./auth.recaptchaverifier.md#recaptchaverifierrender) | | Renders the reCAPTCHA widget on the page. | -| [verify()](./auth.recaptchaverifier.md#recaptchaverifierverify) | | Waits for the user to solve the reCAPTCHA and resolves with the reCAPTCHA token. | - -## RecaptchaVerifier.(constructor) - -Constructs a new instance of the `RecaptchaVerifier` class - -Check the reCAPTCHA docs for a comprehensive list. All parameters are accepted except for the sitekey. Firebase Auth backend provisions a reCAPTCHA for each project and will configure this upon rendering. For an invisible reCAPTCHA, a size key must have the value 'invisible'. - -Signature: - -```typescript -constructor(containerOrId: HTMLElement | string, parameters: RecaptchaParameters, authExtern: Auth); -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| containerOrId | HTMLElement \| string | The reCAPTCHA container parameter. | -| parameters | [RecaptchaParameters](./auth.recaptchaparameters.md#recaptchaparameters_interface) | The optional reCAPTCHA parameters. | -| authExtern | [Auth](./auth.auth.md#auth_interface) | The corresponding Firebase [Auth](./auth.auth.md#auth_interface) instance. | - -## RecaptchaVerifier.type - -The application verifier type. - -For a reCAPTCHA verifier, this is 'recaptcha'. - -Signature: - -```typescript -readonly type = "recaptcha"; -``` - -## RecaptchaVerifier.clear() - -Clears the reCAPTCHA widget from the page and destroys the instance. - -Signature: - -```typescript -clear(): void; -``` -Returns: - -void - -## RecaptchaVerifier.render() - -Renders the reCAPTCHA widget on the page. - -Signature: - -```typescript -render(): Promise; -``` -Returns: - -Promise<number> - -A Promise that resolves with the reCAPTCHA widget ID. - -## RecaptchaVerifier.verify() - -Waits for the user to solve the reCAPTCHA and resolves with the reCAPTCHA token. - -Signature: - -```typescript -verify(): Promise; -``` -Returns: - -Promise<string> - -A Promise for the reCAPTCHA token. - diff --git a/docs-devsite/auth.samlauthprovider.md b/docs-devsite/auth.samlauthprovider.md deleted file mode 100644 index d25dd1999ed..00000000000 --- a/docs-devsite/auth.samlauthprovider.md +++ /dev/null @@ -1,119 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# SAMLAuthProvider class -An [AuthProvider](./auth.authprovider.md#authprovider_interface) for SAML. - -Signature: - -```typescript -export declare class SAMLAuthProvider extends FederatedAuthProvider -``` -Extends: FederatedAuthProvider - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(providerId)](./auth.samlauthprovider.md#samlauthproviderconstructor) | | Constructor. The providerId must start with "saml." | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [credentialFromError(error)](./auth.samlauthprovider.md#samlauthprovidercredentialfromerror) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. | -| [credentialFromJSON(json)](./auth.samlauthprovider.md#samlauthprovidercredentialfromjson) | static | Creates an [AuthCredential](./auth.authcredential.md#authcredential_class) from a JSON string or a plain object. | -| [credentialFromResult(userCredential)](./auth.samlauthprovider.md#samlauthprovidercredentialfromresult) | static | Generates an [AuthCredential](./auth.authcredential.md#authcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface) after a successful SAML flow completes. | - -## SAMLAuthProvider.(constructor) - -Constructor. The providerId must start with "saml." - -Signature: - -```typescript -constructor(providerId: string); -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| providerId | string | SAML provider ID. | - -## SAMLAuthProvider.credentialFromError() - -Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. - -Signature: - -```typescript -static credentialFromError(error: FirebaseError): AuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | | - -Returns: - -[AuthCredential](./auth.authcredential.md#authcredential_class) \| null - -## SAMLAuthProvider.credentialFromJSON() - -Creates an [AuthCredential](./auth.authcredential.md#authcredential_class) from a JSON string or a plain object. - -Signature: - -```typescript -static credentialFromJSON(json: string | object): AuthCredential; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| json | string \| object | A plain object or a JSON string | - -Returns: - -[AuthCredential](./auth.authcredential.md#authcredential_class) - -## SAMLAuthProvider.credentialFromResult() - -Generates an [AuthCredential](./auth.authcredential.md#authcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface) after a successful SAML flow completes. - -For example, to get an [AuthCredential](./auth.authcredential.md#authcredential_class), you could write the following code: - -```js -const userCredential = await signInWithPopup(auth, samlProvider); -const credential = SAMLAuthProvider.credentialFromResult(userCredential); - -``` - -Signature: - -```typescript -static credentialFromResult(userCredential: UserCredential): AuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | - -Returns: - -[AuthCredential](./auth.authcredential.md#authcredential_class) \| null - diff --git a/docs-devsite/auth.twitterauthprovider.md b/docs-devsite/auth.twitterauthprovider.md deleted file mode 100644 index 9ae64b6bdaf..00000000000 --- a/docs-devsite/auth.twitterauthprovider.md +++ /dev/null @@ -1,173 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# TwitterAuthProvider class -Provider for generating an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).TWITTER. - -Signature: - -```typescript -export declare class TwitterAuthProvider extends BaseOAuthProvider -``` -Extends: BaseOAuthProvider - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)()](./auth.twitterauthprovider.md#twitterauthproviderconstructor) | | Constructs a new instance of the TwitterAuthProvider class | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [PROVIDER\_ID](./auth.twitterauthprovider.md#twitterauthproviderprovider_id) | static | 'twitter.com' | Always set to [ProviderId](./auth.md#providerid).TWITTER. | -| [TWITTER\_SIGN\_IN\_METHOD](./auth.twitterauthprovider.md#twitterauthprovidertwitter_sign_in_method) | static | 'twitter.com' | Always set to [SignInMethod](./auth.md#signinmethod).TWITTER. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [credential(token, secret)](./auth.twitterauthprovider.md#twitterauthprovidercredential) | static | Creates a credential for Twitter. | -| [credentialFromError(error)](./auth.twitterauthprovider.md#twitterauthprovidercredentialfromerror) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. | -| [credentialFromResult(userCredential)](./auth.twitterauthprovider.md#twitterauthprovidercredentialfromresult) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). | - -## TwitterAuthProvider.(constructor) - -Constructs a new instance of the `TwitterAuthProvider` class - -Signature: - -```typescript -constructor(); -``` - -## TwitterAuthProvider.PROVIDER\_ID - -Always set to [ProviderId](./auth.md#providerid).TWITTER. - -Signature: - -```typescript -static readonly PROVIDER_ID: 'twitter.com'; -``` - -## TwitterAuthProvider.TWITTER\_SIGN\_IN\_METHOD - -Always set to [SignInMethod](./auth.md#signinmethod).TWITTER. - -Signature: - -```typescript -static readonly TWITTER_SIGN_IN_METHOD: 'twitter.com'; -``` - -## TwitterAuthProvider.credential() - -Creates a credential for Twitter. - -Signature: - -```typescript -static credential(token: string, secret: string): OAuthCredential; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| token | string | Twitter access token. | -| secret | string | Twitter secret. | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) - -## TwitterAuthProvider.credentialFromError() - -Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. - -Signature: - -```typescript -static credentialFromError(error: FirebaseError): OAuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null - -## TwitterAuthProvider.credentialFromResult() - -Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). - -Signature: - -```typescript -static credentialFromResult(userCredential: UserCredential): OAuthCredential | null; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | - -Returns: - -[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null - -### Example 1 - - -```javascript -// Sign in using a redirect. -const provider = new TwitterAuthProvider(); -// Start a sign in process for an unauthenticated user. -await signInWithRedirect(auth, provider); -// This will trigger a full page redirect away from your app - -// After returning from the redirect when your app initializes you can obtain the result -const result = await getRedirectResult(auth); -if (result) { - // This is the signed-in user - const user = result.user; - // This gives you a Twitter Access Token and Secret. - const credential = TwitterAuthProvider.credentialFromResult(result); - const token = credential.accessToken; - const secret = credential.secret; -} - -``` - -### Example 2 - - -```javascript -// Sign in using a popup. -const provider = new TwitterAuthProvider(); -const result = await signInWithPopup(auth, provider); - -// The signed-in user info. -const user = result.user; -// This gives you a Twitter Access Token and Secret. -const credential = TwitterAuthProvider.credentialFromResult(result); -const token = credential.accessToken; -const secret = credential.secret; - -``` - diff --git a/docs-devsite/auth.user.md b/docs-devsite/auth.user.md deleted file mode 100644 index 18a56a45901..00000000000 --- a/docs-devsite/auth.user.md +++ /dev/null @@ -1,204 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# User interface -A user account. - -Signature: - -```typescript -export interface User extends UserInfo -``` -Extends: [UserInfo](./auth.userinfo.md#userinfo_interface) - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [emailVerified](./auth.user.md#useremailverified) | boolean | Whether the email has been verified with [sendEmailVerification()](./auth.md#sendemailverification) and [applyActionCode()](./auth.md#applyactioncode). | -| [isAnonymous](./auth.user.md#userisanonymous) | boolean | Whether the user is authenticated using the [ProviderId](./auth.md#providerid).ANONYMOUS provider. | -| [metadata](./auth.user.md#usermetadata) | [UserMetadata](./auth.usermetadata.md#usermetadata_interface) | Additional metadata around user creation and sign-in times. | -| [providerData](./auth.user.md#userproviderdata) | [UserInfo](./auth.userinfo.md#userinfo_interface)\[\] | Additional per provider such as displayName and profile information. | -| [refreshToken](./auth.user.md#userrefreshtoken) | string | Refresh token used to reauthenticate the user. Avoid using this directly and prefer [User.getIdToken()](./auth.user.md#usergetidtoken) to refresh the ID token instead. | -| [tenantId](./auth.user.md#usertenantid) | string \| null | The user's tenant ID. | - -## Methods - -| Method | Description | -| --- | --- | -| [delete()](./auth.user.md#userdelete) | Deletes and signs out the user. | -| [getIdToken(forceRefresh)](./auth.user.md#usergetidtoken) | Returns a JSON Web Token (JWT) used to identify the user to a Firebase service. | -| [getIdTokenResult(forceRefresh)](./auth.user.md#usergetidtokenresult) | Returns a deserialized JSON Web Token (JWT) used to identitfy the user to a Firebase service. | -| [reload()](./auth.user.md#userreload) | Refreshes the user, if signed in. | -| [toJSON()](./auth.user.md#usertojson) | Returns a JSON-serializable representation of this object. | - -## User.emailVerified - -Whether the email has been verified with [sendEmailVerification()](./auth.md#sendemailverification) and [applyActionCode()](./auth.md#applyactioncode). - -Signature: - -```typescript -readonly emailVerified: boolean; -``` - -## User.isAnonymous - -Whether the user is authenticated using the [ProviderId](./auth.md#providerid).ANONYMOUS provider. - -Signature: - -```typescript -readonly isAnonymous: boolean; -``` - -## User.metadata - -Additional metadata around user creation and sign-in times. - -Signature: - -```typescript -readonly metadata: UserMetadata; -``` - -## User.providerData - -Additional per provider such as displayName and profile information. - -Signature: - -```typescript -readonly providerData: UserInfo[]; -``` - -## User.refreshToken - -Refresh token used to reauthenticate the user. Avoid using this directly and prefer [User.getIdToken()](./auth.user.md#usergetidtoken) to refresh the ID token instead. - -Signature: - -```typescript -readonly refreshToken: string; -``` - -## User.tenantId - -The user's tenant ID. - -This is a read-only property, which indicates the tenant ID used to sign in the user. This is null if the user is signed in from the parent project. - -Signature: - -```typescript -readonly tenantId: string | null; -``` - -### Example - - -```javascript -// Set the tenant ID on Auth instance. -auth.tenantId = 'TENANT_PROJECT_ID'; - -// All future sign-in request now include tenant ID. -const result = await signInWithEmailAndPassword(auth, email, password); -// result.user.tenantId should be 'TENANT_PROJECT_ID'. - -``` - -## User.delete() - -Deletes and signs out the user. - -Important: this is a security-sensitive operation that requires the user to have recently signed in. If this requirement isn't met, ask the user to authenticate again and then call one of the reauthentication methods like [reauthenticateWithCredential()](./auth.md#reauthenticatewithcredential). - -Signature: - -```typescript -delete(): Promise; -``` -Returns: - -Promise<void> - -## User.getIdToken() - -Returns a JSON Web Token (JWT) used to identify the user to a Firebase service. - -Returns the current token if it has not expired or if it will not expire in the next five minutes. Otherwise, this will refresh the token and return a new one. - -Signature: - -```typescript -getIdToken(forceRefresh?: boolean): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| forceRefresh | boolean | Force refresh regardless of token expiration. | - -Returns: - -Promise<string> - -## User.getIdTokenResult() - -Returns a deserialized JSON Web Token (JWT) used to identitfy the user to a Firebase service. - -Returns the current token if it has not expired or if it will not expire in the next five minutes. Otherwise, this will refresh the token and return a new one. - -Signature: - -```typescript -getIdTokenResult(forceRefresh?: boolean): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| forceRefresh | boolean | Force refresh regardless of token expiration. | - -Returns: - -Promise<[IdTokenResult](./auth.idtokenresult.md#idtokenresult_interface)> - -## User.reload() - -Refreshes the user, if signed in. - -Signature: - -```typescript -reload(): Promise; -``` -Returns: - -Promise<void> - -## User.toJSON() - -Returns a JSON-serializable representation of this object. - -Signature: - -```typescript -toJSON(): object; -``` -Returns: - -object - -A JSON-serializable representation of this object. - diff --git a/docs-devsite/auth.usercredential.md b/docs-devsite/auth.usercredential.md deleted file mode 100644 index 665a1ec253e..00000000000 --- a/docs-devsite/auth.usercredential.md +++ /dev/null @@ -1,59 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# UserCredential interface -A structure containing a [User](./auth.user.md#user_interface), the [OperationType](./auth.md#operationtype), and the provider ID. - -`operationType` could be [OperationType](./auth.md#operationtype).SIGN\_IN for a sign-in operation, [OperationType](./auth.md#operationtype).LINK for a linking operation and [OperationType](./auth.md#operationtype).REAUTHENTICATE for a reauthentication operation. - -Signature: - -```typescript -export interface UserCredential -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [operationType](./auth.usercredential.md#usercredentialoperationtype) | typeof [OperationTypeMap](./auth.md#operationtype)\[keyof typeof [OperationTypeMap](./auth.md#operationtype)\] | The type of operation which was used to authenticate the user (such as sign-in or link). | -| [providerId](./auth.usercredential.md#usercredentialproviderid) | string \| null | The provider which was used to authenticate the user. | -| [user](./auth.usercredential.md#usercredentialuser) | [User](./auth.user.md#user_interface) | The user authenticated by this credential. | - -## UserCredential.operationType - -The type of operation which was used to authenticate the user (such as sign-in or link). - -Signature: - -```typescript -operationType: typeof OperationTypeMap[keyof typeof OperationTypeMap]; -``` - -## UserCredential.providerId - -The provider which was used to authenticate the user. - -Signature: - -```typescript -providerId: string | null; -``` - -## UserCredential.user - -The user authenticated by this credential. - -Signature: - -```typescript -user: User; -``` diff --git a/docs-devsite/auth.userinfo.md b/docs-devsite/auth.userinfo.md deleted file mode 100644 index 7b49dc65f9c..00000000000 --- a/docs-devsite/auth.userinfo.md +++ /dev/null @@ -1,92 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# UserInfo interface -User profile information, visible only to the Firebase project's apps. - -Signature: - -```typescript -export interface UserInfo -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [displayName](./auth.userinfo.md#userinfodisplayname) | string \| null | The display name of the user. | -| [email](./auth.userinfo.md#userinfoemail) | string \| null | The email of the user. | -| [phoneNumber](./auth.userinfo.md#userinfophonenumber) | string \| null | The phone number normalized based on the E.164 standard (e.g. +16505550101) for the user. | -| [photoURL](./auth.userinfo.md#userinfophotourl) | string \| null | The profile photo URL of the user. | -| [providerId](./auth.userinfo.md#userinfoproviderid) | string | The provider used to authenticate the user. | -| [uid](./auth.userinfo.md#userinfouid) | string | The user's unique ID, scoped to the project. | - -## UserInfo.displayName - -The display name of the user. - -Signature: - -```typescript -readonly displayName: string | null; -``` - -## UserInfo.email - -The email of the user. - -Signature: - -```typescript -readonly email: string | null; -``` - -## UserInfo.phoneNumber - -The phone number normalized based on the E.164 standard (e.g. +16505550101) for the user. - -This is null if the user has no phone credential linked to the account. - -Signature: - -```typescript -readonly phoneNumber: string | null; -``` - -## UserInfo.photoURL - -The profile photo URL of the user. - -Signature: - -```typescript -readonly photoURL: string | null; -``` - -## UserInfo.providerId - -The provider used to authenticate the user. - -Signature: - -```typescript -readonly providerId: string; -``` - -## UserInfo.uid - -The user's unique ID, scoped to the project. - -Signature: - -```typescript -readonly uid: string; -``` diff --git a/docs-devsite/auth.usermetadata.md b/docs-devsite/auth.usermetadata.md deleted file mode 100644 index bb65b30eff5..00000000000 --- a/docs-devsite/auth.usermetadata.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# UserMetadata interface -Interface representing a user's metadata. - -Signature: - -```typescript -export interface UserMetadata -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [creationTime](./auth.usermetadata.md#usermetadatacreationtime) | string | Time the user was created. | -| [lastSignInTime](./auth.usermetadata.md#usermetadatalastsignintime) | string | Time the user last signed in. | - -## UserMetadata.creationTime - -Time the user was created. - -Signature: - -```typescript -readonly creationTime?: string; -``` - -## UserMetadata.lastSignInTime - -Time the user last signed in. - -Signature: - -```typescript -readonly lastSignInTime?: string; -``` diff --git a/docs-devsite/database.database.md b/docs-devsite/database.database.md deleted file mode 100644 index 62ce4f8a420..00000000000 --- a/docs-devsite/database.database.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Database class -Class representing a Firebase Realtime Database. - -Signature: - -```typescript -export declare class Database -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [app](./database.database.md#databaseapp) | | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this Realtime Database instance. | -| [type](./database.database.md#databasetype) | | (not declared) | Represents a Database instance. | - -## Database.app - -The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this Realtime Database instance. - -Signature: - -```typescript -readonly app: FirebaseApp; -``` - -## Database.type - -Represents a `Database` instance. - -Signature: - -```typescript -readonly 'type' = "database"; -``` diff --git a/docs-devsite/database.databasereference.md b/docs-devsite/database.databasereference.md deleted file mode 100644 index 13f19a3bf4f..00000000000 --- a/docs-devsite/database.databasereference.md +++ /dev/null @@ -1,68 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# DatabaseReference interface -A `DatabaseReference` represents a specific location in your Database and can be used for reading or writing data to that Database location. - -You can reference the root or child location in your Database by calling `ref()` or `ref("child/path")`. - -Writing is done with the `set()` method and reading can be done with the `on*()` method. See [https://firebase.google.com/docs/database/web/read-and-write](https://firebase.google.com/docs/database/web/read-and-write) - -Signature: - -```typescript -export declare interface DatabaseReference extends Query -``` -Extends: [Query](./database.query.md#query_interface) - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [key](./database.databasereference.md#databasereferencekey) | string \| null | The last part of the DatabaseReference's path.For example, "ada" is the key for https://<DATABASE_NAME>.firebaseio.com/users/ada.The key of a root DatabaseReference is null. | -| [parent](./database.databasereference.md#databasereferenceparent) | [DatabaseReference](./database.databasereference.md#databasereference_interface) \| null | The parent location of a DatabaseReference.The parent of a root DatabaseReference is null. | -| [root](./database.databasereference.md#databasereferenceroot) | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The root DatabaseReference of the Database. | - -## DatabaseReference.key - -The last part of the `DatabaseReference`'s path. - -For example, `"ada"` is the key for `https://.firebaseio.com/users/ada`. - -The key of a root `DatabaseReference` is `null`. - -Signature: - -```typescript -readonly key: string | null; -``` - -## DatabaseReference.parent - -The parent location of a `DatabaseReference`. - -The parent of a root `DatabaseReference` is `null`. - -Signature: - -```typescript -readonly parent: DatabaseReference | null; -``` - -## DatabaseReference.root - -The root `DatabaseReference` of the Database. - -Signature: - -```typescript -readonly root: DatabaseReference; -``` diff --git a/docs-devsite/database.datasnapshot.md b/docs-devsite/database.datasnapshot.md deleted file mode 100644 index 35e983def87..00000000000 --- a/docs-devsite/database.datasnapshot.md +++ /dev/null @@ -1,237 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# DataSnapshot class -A `DataSnapshot` contains data from a Database location. - -Any time you read data from the Database, you receive the data as a `DataSnapshot`. A `DataSnapshot` is passed to the event callbacks you attach with `on()` or `once()`. You can extract the contents of the snapshot as a JavaScript object by calling the `val()` method. Alternatively, you can traverse into the snapshot by calling `child()` to return child snapshots (which you could then call `val()` on). - -A `DataSnapshot` is an efficiently generated, immutable copy of the data at a Database location. It cannot be modified and will never change (to modify data, you always call the `set()` method on a `Reference` directly). - -Signature: - -```typescript -export declare class DataSnapshot -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [key](./database.datasnapshot.md#datasnapshotkey) | | string \| null | The key (last part of the path) of the location of this DataSnapshot.The last token in a Database location is considered its key. For example, "ada" is the key for the /users/ada/ node. Accessing the key on any DataSnapshot will return the key for the location that generated it. However, accessing the key on the root URL of a Database will return null. | -| [priority](./database.datasnapshot.md#datasnapshotpriority) | | string \| number \| null | Gets the priority value of the data in this DataSnapshot.Applications need not use priority but can order collections by ordinary properties (see [Sorting and filtering data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) ). | -| [ref](./database.datasnapshot.md#datasnapshotref) | | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location of this DataSnapshot. | -| [size](./database.datasnapshot.md#datasnapshotsize) | | number | Returns the number of child properties of this DataSnapshot. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [child(path)](./database.datasnapshot.md#datasnapshotchild) | | Gets another DataSnapshot for the location at the specified relative path.Passing a relative path to the child() method of a DataSnapshot returns another DataSnapshot for the location at the specified relative path. The relative path can either be a simple child name (for example, "ada") or a deeper, slash-separated path (for example, "ada/name/first"). If the child location has no data, an empty DataSnapshot (that is, a DataSnapshot whose value is null) is returned. | -| [exists()](./database.datasnapshot.md#datasnapshotexists) | | Returns true if this DataSnapshot contains any data. It is slightly more efficient than using snapshot.val() !== null. | -| [exportVal()](./database.datasnapshot.md#datasnapshotexportval) | | Exports the entire contents of the DataSnapshot as a JavaScript object.The exportVal() method is similar to val(), except priority information is included (if available), making it suitable for backing up your data. | -| [forEach(action)](./database.datasnapshot.md#datasnapshotforeach) | | Enumerates the top-level children in the DataSnapshot.Because of the way JavaScript objects work, the ordering of data in the JavaScript object returned by val() is not guaranteed to match the ordering on the server nor the ordering of onChildAdded() events. That is where forEach() comes in handy. It guarantees the children of a DataSnapshot will be iterated in their query order.If no explicit orderBy*() method is used, results are returned ordered by key (unless priorities are used, in which case, results are returned by priority). | -| [hasChild(path)](./database.datasnapshot.md#datasnapshothaschild) | | Returns true if the specified child path has (non-null) data. | -| [hasChildren()](./database.datasnapshot.md#datasnapshothaschildren) | | Returns whether or not the DataSnapshot has any non-null child properties.You can use hasChildren() to determine if a DataSnapshot has any children. If it does, you can enumerate them using forEach(). If it doesn't, then either this snapshot contains a primitive value (which can be retrieved with val()) or it is empty (in which case, val() will return null). | -| [toJSON()](./database.datasnapshot.md#datasnapshottojson) | | Returns a JSON-serializable representation of this object. | -| [val()](./database.datasnapshot.md#datasnapshotval) | | Extracts a JavaScript value from a DataSnapshot.Depending on the data in a DataSnapshot, the val() method may return a scalar type (string, number, or boolean), an array, or an object. It may also return null, indicating that the DataSnapshot is empty (contains no data). | - -## DataSnapshot.key - -The key (last part of the path) of the location of this `DataSnapshot`. - -The last token in a Database location is considered its key. For example, "ada" is the key for the /users/ada/ node. Accessing the key on any `DataSnapshot` will return the key for the location that generated it. However, accessing the key on the root URL of a Database will return `null`. - -Signature: - -```typescript -get key(): string | null; -``` - -## DataSnapshot.priority - -Gets the priority value of the data in this `DataSnapshot`. - -Applications need not use priority but can order collections by ordinary properties (see [Sorting and filtering data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) ). - -Signature: - -```typescript -get priority(): string | number | null; -``` - -## DataSnapshot.ref - -The location of this DataSnapshot. - -Signature: - -```typescript -readonly ref: DatabaseReference; -``` - -## DataSnapshot.size - -Returns the number of child properties of this `DataSnapshot`. - -Signature: - -```typescript -get size(): number; -``` - -## DataSnapshot.child() - -Gets another `DataSnapshot` for the location at the specified relative path. - -Passing a relative path to the `child()` method of a DataSnapshot returns another `DataSnapshot` for the location at the specified relative path. The relative path can either be a simple child name (for example, "ada") or a deeper, slash-separated path (for example, "ada/name/first"). If the child location has no data, an empty `DataSnapshot` (that is, a `DataSnapshot` whose value is `null`) is returned. - -Signature: - -```typescript -child(path: string): DataSnapshot; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| path | string | A relative path to the location of child data. | - -Returns: - -[DataSnapshot](./database.datasnapshot.md#datasnapshot_class) - -## DataSnapshot.exists() - -Returns true if this `DataSnapshot` contains any data. It is slightly more efficient than using `snapshot.val() !== null`. - -Signature: - -```typescript -exists(): boolean; -``` -Returns: - -boolean - -## DataSnapshot.exportVal() - -Exports the entire contents of the DataSnapshot as a JavaScript object. - -The `exportVal()` method is similar to `val()`, except priority information is included (if available), making it suitable for backing up your data. - -Signature: - -```typescript -exportVal(): any; -``` -Returns: - -any - -The DataSnapshot's contents as a JavaScript value (Object, Array, string, number, boolean, or `null`). - -## DataSnapshot.forEach() - -Enumerates the top-level children in the `DataSnapshot`. - -Because of the way JavaScript objects work, the ordering of data in the JavaScript object returned by `val()` is not guaranteed to match the ordering on the server nor the ordering of `onChildAdded()` events. That is where `forEach()` comes in handy. It guarantees the children of a `DataSnapshot` will be iterated in their query order. - -If no explicit `orderBy*()` method is used, results are returned ordered by key (unless priorities are used, in which case, results are returned by priority). - -Signature: - -```typescript -forEach(action: (child: DataSnapshot) => boolean | void): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| action | (child: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => boolean \| void | A function that will be called for each child DataSnapshot. The callback can return true to cancel further enumeration. | - -Returns: - -boolean - -true if enumeration was canceled due to your callback returning true. - -## DataSnapshot.hasChild() - -Returns true if the specified child path has (non-null) data. - -Signature: - -```typescript -hasChild(path: string): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| path | string | A relative path to the location of a potential child. | - -Returns: - -boolean - -`true` if data exists at the specified child path; else `false`. - -## DataSnapshot.hasChildren() - -Returns whether or not the `DataSnapshot` has any non-`null` child properties. - -You can use `hasChildren()` to determine if a `DataSnapshot` has any children. If it does, you can enumerate them using `forEach()`. If it doesn't, then either this snapshot contains a primitive value (which can be retrieved with `val()`) or it is empty (in which case, `val()` will return `null`). - -Signature: - -```typescript -hasChildren(): boolean; -``` -Returns: - -boolean - -true if this snapshot has any children; else false. - -## DataSnapshot.toJSON() - -Returns a JSON-serializable representation of this object. - -Signature: - -```typescript -toJSON(): object | null; -``` -Returns: - -object \| null - -## DataSnapshot.val() - -Extracts a JavaScript value from a `DataSnapshot`. - -Depending on the data in a `DataSnapshot`, the `val()` method may return a scalar type (string, number, or boolean), an array, or an object. It may also return null, indicating that the `DataSnapshot` is empty (contains no data). - -Signature: - -```typescript -val(): any; -``` -Returns: - -any - -The DataSnapshot's contents as a JavaScript value (Object, Array, string, number, boolean, or `null`). - diff --git a/docs-devsite/database.listenoptions.md b/docs-devsite/database.listenoptions.md deleted file mode 100644 index 171067dd020..00000000000 --- a/docs-devsite/database.listenoptions.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ListenOptions interface -An options objects that can be used to customize a listener. - -Signature: - -```typescript -export declare interface ListenOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [onlyOnce](./database.listenoptions.md#listenoptionsonlyonce) | boolean | Whether to remove the listener after its first invocation. | - -## ListenOptions.onlyOnce - -Whether to remove the listener after its first invocation. - -Signature: - -```typescript -readonly onlyOnce?: boolean; -``` diff --git a/docs-devsite/database.md b/docs-devsite/database.md deleted file mode 100644 index 686ca7f8580..00000000000 --- a/docs-devsite/database.md +++ /dev/null @@ -1,1405 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# database package -Firebase Realtime Database - -## Functions - -| Function | Description | -| --- | --- | -| function(app...) | -| [getDatabase(app, url)](./database.md#getdatabase) | Returns the instance of the Realtime Database SDK that is associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). Initializes a new instance with with default settings if no instance exists or if the existing instance uses a custom database URL. | -| function(db...) | -| [connectDatabaseEmulator(db, host, port, options)](./database.md#connectdatabaseemulator) | Modify the provided instance to communicate with the Realtime Database emulator.

Note: This method must be called before performing any other operation. | -| [goOffline(db)](./database.md#gooffline) | Disconnects from the server (all Database operations will be completed offline).The client automatically maintains a persistent connection to the Database server, which will remain active indefinitely and reconnect when disconnected. However, the goOffline() and goOnline() methods may be used to control the client connection in cases where a persistent connection is undesirable.While offline, the client will no longer receive data updates from the Database. However, all Database operations performed locally will continue to immediately fire events, allowing your application to continue behaving normally. Additionally, each operation performed locally will automatically be queued and retried upon reconnection to the Database server.To reconnect to the Database and begin receiving remote events, see goOnline(). | -| [goOnline(db)](./database.md#goonline) | Reconnects to the server and synchronizes the offline Database state with the server state.This method should be used after disabling the active connection with goOffline(). Once reconnected, the client will transmit the proper data and fire the appropriate events so that your client "catches up" automatically. | -| [ref(db, path)](./database.md#ref) | Returns a Reference representing the location in the Database corresponding to the provided path. If no path is provided, the Reference will point to the root of the Database. | -| [refFromURL(db, url)](./database.md#reffromurl) | Returns a Reference representing the location in the Database corresponding to the provided Firebase URL.An exception is thrown if the URL is not a valid Firebase Database URL or it has a different domain than the current Database instance.Note that all query parameters (orderBy, limitToLast, etc.) are ignored and are not applied to the returned Reference. | -| function() | -| [forceLongPolling()](./database.md#forcelongpolling) | Force the use of longPolling instead of websockets. This will be ignored if websocket protocol is used in databaseURL. | -| [forceWebSockets()](./database.md#forcewebsockets) | Force the use of websockets instead of longPolling. | -| [orderByKey()](./database.md#orderbykey) | Creates a new QueryConstraint that orders by the key.Sorts the results of a query by their (ascending) key values.You can read more about orderByKey() in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). | -| [orderByPriority()](./database.md#orderbypriority) | Creates a new QueryConstraint that orders by priority.Applications need not use priority but can order collections by ordinary properties (see [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data) for alternatives to priority. | -| [orderByValue()](./database.md#orderbyvalue) | Creates a new QueryConstraint that orders by value.If the children of a query are all scalar values (string, number, or boolean), you can order the results by their (ascending) values.You can read more about orderByValue() in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). | -| [serverTimestamp()](./database.md#servertimestamp) | Returns a placeholder value for auto-populating the current timestamp (time since the Unix epoch, in milliseconds) as determined by the Firebase servers. | -| function(delta...) | -| [increment(delta)](./database.md#increment) | Returns a placeholder value that can be used to atomically increment the current database value by the provided delta. | -| function(enabled...) | -| [enableLogging(enabled, persistent)](./database.md#enablelogging) | Logs debugging information to the console. | -| function(limit...) | -| [limitToFirst(limit)](./database.md#limittofirst) | Creates a new QueryConstraint that if limited to the first specific number of children.The limitToFirst() method is used to set a maximum number of children to be synced for a given callback. If we set a limit of 100, we will initially only receive up to 100 child_added events. If we have fewer than 100 messages stored in our Database, a child_added event will fire for each message. However, if we have over 100 messages, we will only receive a child_added event for the first 100 ordered messages. As items change, we will receive child_removed events for each item that drops out of the active list so that the total number stays at 100.You can read more about limitToFirst() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | -| [limitToLast(limit)](./database.md#limittolast) | Creates a new QueryConstraint that is limited to return only the last specified number of children.The limitToLast() method is used to set a maximum number of children to be synced for a given callback. If we set a limit of 100, we will initially only receive up to 100 child_added events. If we have fewer than 100 messages stored in our Database, a child_added event will fire for each message. However, if we have over 100 messages, we will only receive a child_added event for the last 100 ordered messages. As items change, we will receive child_removed events for each item that drops out of the active list so that the total number stays at 100.You can read more about limitToLast() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | -| function(logger...) | -| [enableLogging(logger)](./database.md#enablelogging) | Logs debugging information to the console. | -| function(parent...) | -| [child(parent, path)](./database.md#child) | Gets a Reference for the location at the specified relative path.The relative path can either be a simple child name (for example, "ada") or a deeper slash-separated path (for example, "ada/name/first"). | -| [push(parent, value)](./database.md#push) | Generates a new child location using a unique key and returns its Reference.This is the most common pattern for adding data to a collection of items.If you provide a value to push(), the value is written to the generated location. If you don't pass a value, nothing is written to the database and the child remains empty (but you can use the Reference elsewhere).The unique keys generated by push() are ordered by the current time, so the resulting list of items is chronologically sorted. The keys are also designed to be unguessable (they contain 72 random bits of entropy).See [Append to a list of data](https://firebase.google.com/docs/database/web/lists-of-data#append_to_a_list_of_data). See [The 2^120 Ways to Ensure Unique Identifiers](https://firebase.googleblog.com/2015/02/the-2120-ways-to-ensure-unique_68.html). | -| function(path...) | -| [orderByChild(path)](./database.md#orderbychild) | Creates a new QueryConstraint that orders by the specified child key.Queries can only order by one key at a time. Calling orderByChild() multiple times on the same query is an error.Firebase queries allow you to order your data by any child key on the fly. However, if you know in advance what your indexes will be, you can define them via the .indexOn rule in your Security Rules for better performance. See the[https://firebase.google.com/docs/database/security/indexing-data](https://firebase.google.com/docs/database/security/indexing-data) rule for more information.You can read more about orderByChild() in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). | -| function(query...) | -| [get(query)](./database.md#get) | Gets the most up-to-date result for this query. | -| [off(query, eventType, callback)](./database.md#off) | Detaches a callback previously attached with the corresponding on*() (onValue, onChildAdded) listener. Note: This is not the recommended way to remove a listener. Instead, please use the returned callback function from the respective on* callbacks.Detach a callback previously attached with on*(). Calling off() on a parent listener will not automatically remove listeners registered on child nodes, off() must also be called on any child listeners to remove the callback.If a callback is not specified, all callbacks for the specified eventType will be removed. Similarly, if no eventType is specified, all callbacks for the Reference will be removed.Individual listeners can also be removed by invoking their unsubscribe callbacks. | -| [onChildAdded(query, callback, cancelCallback)](./database.md#onchildadded) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildAdded event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The DataSnapshot passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | -| [onChildAdded(query, callback, options)](./database.md#onchildadded) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildAdded event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The DataSnapshot passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | -| [onChildAdded(query, callback, cancelCallback, options)](./database.md#onchildadded) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildAdded event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The DataSnapshot passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | -| [onChildChanged(query, callback, cancelCallback)](./database.md#onchildchanged) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildChanged event will be triggered when the data stored in a child (or any of its descendants) changes. Note that a single child_changed event may represent multiple changes to the child. The DataSnapshot passed to the callback will contain the new child contents. For ordering purposes, the callback is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | -| [onChildChanged(query, callback, options)](./database.md#onchildchanged) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildChanged event will be triggered when the data stored in a child (or any of its descendants) changes. Note that a single child_changed event may represent multiple changes to the child. The DataSnapshot passed to the callback will contain the new child contents. For ordering purposes, the callback is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | -| [onChildChanged(query, callback, cancelCallback, options)](./database.md#onchildchanged) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildChanged event will be triggered when the data stored in a child (or any of its descendants) changes. Note that a single child_changed event may represent multiple changes to the child. The DataSnapshot passed to the callback will contain the new child contents. For ordering purposes, the callback is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | -| [onChildMoved(query, callback, cancelCallback)](./database.md#onchildmoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildMoved event will be triggered when a child's sort order changes such that its position relative to its siblings changes. The DataSnapshot passed to the callback will be for the data of the child that has moved. It is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | -| [onChildMoved(query, callback, options)](./database.md#onchildmoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildMoved event will be triggered when a child's sort order changes such that its position relative to its siblings changes. The DataSnapshot passed to the callback will be for the data of the child that has moved. It is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | -| [onChildMoved(query, callback, cancelCallback, options)](./database.md#onchildmoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildMoved event will be triggered when a child's sort order changes such that its position relative to its siblings changes. The DataSnapshot passed to the callback will be for the data of the child that has moved. It is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | -| [onChildRemoved(query, callback, cancelCallback)](./database.md#onchildremoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildRemoved event will be triggered once every time a child is removed. The DataSnapshot passed into the callback will be the old data for the child that was removed. A child will get removed when either:- a client explicitly calls remove() on that child or one of its ancestors - a client calls set(null) on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) | -| [onChildRemoved(query, callback, options)](./database.md#onchildremoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildRemoved event will be triggered once every time a child is removed. The DataSnapshot passed into the callback will be the old data for the child that was removed. A child will get removed when either:- a client explicitly calls remove() on that child or one of its ancestors - a client calls set(null) on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) | -| [onChildRemoved(query, callback, cancelCallback, options)](./database.md#onchildremoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildRemoved event will be triggered once every time a child is removed. The DataSnapshot passed into the callback will be the old data for the child that was removed. A child will get removed when either:- a client explicitly calls remove() on that child or one of its ancestors - a client calls set(null) on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) | -| [onValue(query, callback, cancelCallback)](./database.md#onvalue) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onValue event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The DataSnapshot passed to the callback will be for the location at which on() was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty DataSnapshot (val() will return null). | -| [onValue(query, callback, options)](./database.md#onvalue) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onValue event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The DataSnapshot passed to the callback will be for the location at which on() was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty DataSnapshot (val() will return null). | -| [onValue(query, callback, cancelCallback, options)](./database.md#onvalue) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onValue event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The DataSnapshot passed to the callback will be for the location at which on() was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty DataSnapshot (val() will return null). | -| [query(query, queryConstraints)](./database.md#query) | Creates a new immutable instance of Query that is extended to also include additional query constraints. | -| function(ref...) | -| [onDisconnect(ref)](./database.md#ondisconnect) | Returns an OnDisconnect object - see [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information on how to use it. | -| [remove(ref)](./database.md#remove) | Removes the data at this Database location.Any data at child locations will also be deleted.The effect of the remove will be visible immediately and the corresponding event 'value' will be triggered. Synchronization of the remove to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the onComplete callback will be called asynchronously after synchronization has finished. | -| [runTransaction(ref, transactionUpdate, options)](./database.md#runtransaction) | Atomically modifies the data at this location.Atomically modify the data at this location. Unlike a normal set(), which just overwrites the data regardless of its previous value, runTransaction() is used to modify the existing value to a new value, ensuring there are no conflicts with other clients writing to the same location at the same time.To accomplish this, you pass runTransaction() an update function which is used to transform the current value into a new value. If another client writes to the location before your new value is successfully written, your update function will be called again with the new current value, and the write will be retried. This will happen repeatedly until your write succeeds without conflict or you abort the transaction by not returning a value from your update function.Note: Modifying data with set() will cancel any pending transactions at that location, so extreme care should be taken if mixing set() and runTransaction() to update the same data.Note: When using transactions with Security and Firebase Rules in place, be aware that a client needs .read access in addition to .write access in order to perform a transaction. This is because the client-side nature of transactions requires the client to read the data in order to transactionally update it. | -| [set(ref, value)](./database.md#set) | Writes data to this Database location.This will overwrite any data at this location and all child locations.The effect of the write will be visible immediately, and the corresponding events ("value", "child\_added", etc.) will be triggered. Synchronization of the data to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the onComplete callback will be called asynchronously after synchronization has finished.Passing null for the new value is equivalent to calling remove(); namely, all data at this location and all child locations will be deleted.set() will remove any priority stored at this location, so if priority is meant to be preserved, you need to use setWithPriority() instead.Note that modifying data with set() will cancel any pending transactions at that location, so extreme care should be taken if mixing set() and transaction() to modify the same data.A single set() will generate a single "value" event at the location where the set() was performed. | -| [setPriority(ref, priority)](./database.md#setpriority) | Sets a priority for the data at this Database location.Applications need not use priority but can order collections by ordinary properties (see [Sorting and filtering data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) ). | -| [setWithPriority(ref, value, priority)](./database.md#setwithpriority) | Writes data the Database location. Like set() but also specifies the priority for that data.Applications need not use priority but can order collections by ordinary properties (see [Sorting and filtering data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) ). | -| [update(ref, values)](./database.md#update) | Writes multiple values to the Database at once.The values argument contains multiple property-value pairs that will be written to the Database together. Each child property can either be a simple property (for example, "name") or a relative path (for example, "name/first") from the current location to the data to update.As opposed to the set() method, update() can be use to selectively update only the referenced properties at the current location (instead of replacing all the child properties at the current location).The effect of the write will be visible immediately, and the corresponding events ('value', 'child\_added', etc.) will be triggered. Synchronization of the data to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the onComplete callback will be called asynchronously after synchronization has finished.A single update() will generate a single "value" event at the location where the update() was performed, regardless of how many children were modified.Note that modifying data with update() will cancel any pending transactions at that location, so extreme care should be taken if mixing update() and transaction() to modify the same data.Passing null to update() will remove the data at this location.See [Introducing multi-location updates and more](https://firebase.googleblog.com/2015/09/introducing-multi-location-updates-and_86.html). | -| function(value...) | -| [endAt(value, key)](./database.md#endat) | Creates a QueryConstraint with the specified ending point.Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The ending point is inclusive, so children with exactly the specified value will be included in the query. The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have a key name less than or equal to the specified key.You can read more about endAt() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | -| [endBefore(value, key)](./database.md#endbefore) | Creates a QueryConstraint with the specified ending point (exclusive).Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The ending point is exclusive. If only a value is provided, children with a value less than the specified value will be included in the query. If a key is specified, then children must have a value less than or equal to the specified value and a key name less than the specified key. | -| [equalTo(value, key)](./database.md#equalto) | Creates a QueryConstraint that includes children that match the specified value.Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have exactly the specified key as their key name. This can be used to filter result sets with many matches for the same value.You can read more about equalTo() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | -| [startAfter(value, key)](./database.md#startafter) | Creates a QueryConstraint with the specified starting point (exclusive).Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The starting point is exclusive. If only a value is provided, children with a value greater than the specified value will be included in the query. If a key is specified, then children must have a value greater than or equal to the specified value and a a key name greater than the specified key. | -| [startAt(value, key)](./database.md#startat) | Creates a QueryConstraint with the specified starting point.Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The starting point is inclusive, so children with exactly the specified value will be included in the query. The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have a key name greater than or equal to the specified key.You can read more about startAt() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | - -## Classes - -| Class | Description | -| --- | --- | -| [Database](./database.database.md#database_class) | Class representing a Firebase Realtime Database. | -| [DataSnapshot](./database.datasnapshot.md#datasnapshot_class) | A DataSnapshot contains data from a Database location.Any time you read data from the Database, you receive the data as a DataSnapshot. A DataSnapshot is passed to the event callbacks you attach with on() or once(). You can extract the contents of the snapshot as a JavaScript object by calling the val() method. Alternatively, you can traverse into the snapshot by calling child() to return child snapshots (which you could then call val() on).A DataSnapshot is an efficiently generated, immutable copy of the data at a Database location. It cannot be modified and will never change (to modify data, you always call the set() method on a Reference directly). | -| [OnDisconnect](./database.ondisconnect.md#ondisconnect_class) | The onDisconnect class allows you to write or clear data when your client disconnects from the Database server. These updates occur whether your client disconnects cleanly or not, so you can rely on them to clean up data even if a connection is dropped or a client crashes.The onDisconnect class is most commonly used to manage presence in applications where it is useful to detect how many clients are connected and when other clients disconnect. See [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information.To avoid problems when a connection is dropped before the requests can be transferred to the Database server, these functions should be called before writing any data.Note that onDisconnect operations are only triggered once. If you want an operation to occur each time a disconnect occurs, you'll need to re-establish the onDisconnect operations each time you reconnect. | -| [QueryConstraint](./database.queryconstraint.md#queryconstraint_class) | A QueryConstraint is used to narrow the set of documents returned by a Database query. QueryConstraints are created by invoking [endAt()](./database.md#endat), [endBefore()](./database.md#endbefore), [startAt()](./database.md#startat), [startAfter()](./database.md#startafter), [limitToFirst()](./database.md#limittofirst), [limitToLast()](./database.md#limittolast), [orderByChild()](./database.md#orderbychild), [orderByChild()](./database.md#orderbychild), [orderByKey()](./database.md#orderbykey) , [orderByPriority()](./database.md#orderbypriority) , [orderByValue()](./database.md#orderbyvalue) or [equalTo()](./database.md#equalto) and can then be passed to [query()](./database.md#query) to create a new query instance that also contains this QueryConstraint. | -| [TransactionResult](./database.transactionresult.md#transactionresult_class) | A type for the resolve value of [runTransaction()](./database.md#runtransaction). | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [DatabaseReference](./database.databasereference.md#databasereference_interface) | A DatabaseReference represents a specific location in your Database and can be used for reading or writing data to that Database location.You can reference the root or child location in your Database by calling ref() or ref("child/path").Writing is done with the set() method and reading can be done with the on*() method. See [https://firebase.google.com/docs/database/web/read-and-write](https://firebase.google.com/docs/database/web/read-and-write) | -| [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An options objects that can be used to customize a listener. | -| [Query](./database.query.md#query_interface) | A Query sorts and filters the data at a Database location so only a subset of the child data is included. This can be used to order a collection of data by some attribute (for example, height of dinosaurs) as well as to restrict a large list of items (for example, chat messages) down to a number suitable for synchronizing to the client. Queries are created by chaining together one or more of the filter methods defined here.Just as with a DatabaseReference, you can receive data from a Query by using the on*() methods. You will only receive events and DataSnapshots for the subset of the data that matches your query.See [https://firebase.google.com/docs/database/web/lists-of-data\#sorting\_and\_filtering\_data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) for more information. | -| [ThenableReference](./database.thenablereference.md#thenablereference_interface) | A Promise that can also act as a DatabaseReference when returned by [push()](./database.md#push). The reference is available immediately and the Promise resolves as the write to the backend completes. | -| [TransactionOptions](./database.transactionoptions.md#transactionoptions_interface) | An options object to configure transactions. | - -## Type Aliases - -| Type Alias | Description | -| --- | --- | -| [EventType](./database.md#eventtype) | One of the following strings: "value", "child\_added", "child\_changed", "child\_removed", or "child\_moved." | -| [QueryConstraintType](./database.md#queryconstrainttype) | Describes the different query constraints available in this SDK. | -| [Unsubscribe](./database.md#unsubscribe) | A callback that can invoked to remove a listener. | - -## getDatabase() - -Returns the instance of the Realtime Database SDK that is associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). Initializes a new instance with with default settings if no instance exists or if the existing instance uses a custom database URL. - -Signature: - -```typescript -export declare function getDatabase(app?: FirebaseApp, url?: string): Database; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance that the returned Realtime Database instance is associated with. | -| url | string | The URL of the Realtime Database instance to connect to. If not provided, the SDK connects to the default instance of the Firebase App. | - -Returns: - -[Database](./database.database.md#database_class) - -The `Database` instance of the provided app. - -## connectDatabaseEmulator() - -Modify the provided instance to communicate with the Realtime Database emulator. - -

Note: This method must be called before performing any other operation. - -Signature: - -```typescript -export declare function connectDatabaseEmulator(db: Database, host: string, port: number, options?: { - mockUserToken?: EmulatorMockTokenOptions | string; -}): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| db | [Database](./database.database.md#database_class) | The instance to modify. | -| host | string | The emulator host (ex: localhost) | -| port | number | The emulator port (ex: 8080) | -| options | { mockUserToken?: [EmulatorMockTokenOptions](./util.md#emulatormocktokenoptions) \| string; } | | - -Returns: - -void - -## goOffline() - -Disconnects from the server (all Database operations will be completed offline). - -The client automatically maintains a persistent connection to the Database server, which will remain active indefinitely and reconnect when disconnected. However, the `goOffline()` and `goOnline()` methods may be used to control the client connection in cases where a persistent connection is undesirable. - -While offline, the client will no longer receive data updates from the Database. However, all Database operations performed locally will continue to immediately fire events, allowing your application to continue behaving normally. Additionally, each operation performed locally will automatically be queued and retried upon reconnection to the Database server. - -To reconnect to the Database and begin receiving remote events, see `goOnline()`. - -Signature: - -```typescript -export declare function goOffline(db: Database): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| db | [Database](./database.database.md#database_class) | The instance to disconnect. | - -Returns: - -void - -## goOnline() - -Reconnects to the server and synchronizes the offline Database state with the server state. - -This method should be used after disabling the active connection with `goOffline()`. Once reconnected, the client will transmit the proper data and fire the appropriate events so that your client "catches up" automatically. - -Signature: - -```typescript -export declare function goOnline(db: Database): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| db | [Database](./database.database.md#database_class) | The instance to reconnect. | - -Returns: - -void - -## ref() - -Returns a `Reference` representing the location in the Database corresponding to the provided path. If no path is provided, the `Reference` will point to the root of the Database. - -Signature: - -```typescript -export declare function ref(db: Database, path?: string): DatabaseReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| db | [Database](./database.database.md#database_class) | The database instance to obtain a reference for. | -| path | string | Optional path representing the location the returned Reference will point. If not provided, the returned Reference will point to the root of the Database. | - -Returns: - -[DatabaseReference](./database.databasereference.md#databasereference_interface) - -If a path is provided, a `Reference` pointing to the provided path. Otherwise, a `Reference` pointing to the root of the Database. - -## refFromURL() - -Returns a `Reference` representing the location in the Database corresponding to the provided Firebase URL. - -An exception is thrown if the URL is not a valid Firebase Database URL or it has a different domain than the current `Database` instance. - -Note that all query parameters (`orderBy`, `limitToLast`, etc.) are ignored and are not applied to the returned `Reference`. - -Signature: - -```typescript -export declare function refFromURL(db: Database, url: string): DatabaseReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| db | [Database](./database.database.md#database_class) | The database instance to obtain a reference for. | -| url | string | The Firebase URL at which the returned Reference will point. | - -Returns: - -[DatabaseReference](./database.databasereference.md#databasereference_interface) - -A `Reference` pointing to the provided Firebase URL. - -## forceLongPolling() - -Force the use of longPolling instead of websockets. This will be ignored if websocket protocol is used in databaseURL. - -Signature: - -```typescript -export declare function forceLongPolling(): void; -``` -Returns: - -void - -## forceWebSockets() - -Force the use of websockets instead of longPolling. - -Signature: - -```typescript -export declare function forceWebSockets(): void; -``` -Returns: - -void - -## orderByKey() - -Creates a new `QueryConstraint` that orders by the key. - -Sorts the results of a query by their (ascending) key values. - -You can read more about `orderByKey()` in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). - -Signature: - -```typescript -export declare function orderByKey(): QueryConstraint; -``` -Returns: - -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) - -## orderByPriority() - -Creates a new `QueryConstraint` that orders by priority. - -Applications need not use priority but can order collections by ordinary properties (see [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data) for alternatives to priority. - -Signature: - -```typescript -export declare function orderByPriority(): QueryConstraint; -``` -Returns: - -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) - -## orderByValue() - -Creates a new `QueryConstraint` that orders by value. - -If the children of a query are all scalar values (string, number, or boolean), you can order the results by their (ascending) values. - -You can read more about `orderByValue()` in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). - -Signature: - -```typescript -export declare function orderByValue(): QueryConstraint; -``` -Returns: - -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) - -## serverTimestamp() - -Returns a placeholder value for auto-populating the current timestamp (time since the Unix epoch, in milliseconds) as determined by the Firebase servers. - -Signature: - -```typescript -export declare function serverTimestamp(): object; -``` -Returns: - -object - -## increment() - -Returns a placeholder value that can be used to atomically increment the current database value by the provided delta. - -Signature: - -```typescript -export declare function increment(delta: number): object; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| delta | number | the amount to modify the current value atomically. | - -Returns: - -object - -A placeholder value for modifying data atomically server-side. - -## enableLogging() - -Logs debugging information to the console. - -Signature: - -```typescript -export declare function enableLogging(enabled: boolean, persistent?: boolean): any; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| enabled | boolean | Enables logging if true, disables logging if false. | -| persistent | boolean | Remembers the logging state between page refreshes if true. | - -Returns: - -any - -## limitToFirst() - -Creates a new `QueryConstraint` that if limited to the first specific number of children. - -The `limitToFirst()` method is used to set a maximum number of children to be synced for a given callback. If we set a limit of 100, we will initially only receive up to 100 `child_added` events. If we have fewer than 100 messages stored in our Database, a `child_added` event will fire for each message. However, if we have over 100 messages, we will only receive a `child_added` event for the first 100 ordered messages. As items change, we will receive `child_removed` events for each item that drops out of the active list so that the total number stays at 100. - -You can read more about `limitToFirst()` in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). - -Signature: - -```typescript -export declare function limitToFirst(limit: number): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| limit | number | The maximum number of nodes to include in this query. | - -Returns: - -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) - -## limitToLast() - -Creates a new `QueryConstraint` that is limited to return only the last specified number of children. - -The `limitToLast()` method is used to set a maximum number of children to be synced for a given callback. If we set a limit of 100, we will initially only receive up to 100 `child_added` events. If we have fewer than 100 messages stored in our Database, a `child_added` event will fire for each message. However, if we have over 100 messages, we will only receive a `child_added` event for the last 100 ordered messages. As items change, we will receive `child_removed` events for each item that drops out of the active list so that the total number stays at 100. - -You can read more about `limitToLast()` in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). - -Signature: - -```typescript -export declare function limitToLast(limit: number): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| limit | number | The maximum number of nodes to include in this query. | - -Returns: - -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) - -## enableLogging() - -Logs debugging information to the console. - -Signature: - -```typescript -export declare function enableLogging(logger: (message: string) => unknown): any; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| logger | (message: string) => unknown | A custom logger function to control how things get logged. | - -Returns: - -any - -## child() - -Gets a `Reference` for the location at the specified relative path. - -The relative path can either be a simple child name (for example, "ada") or a deeper slash-separated path (for example, "ada/name/first"). - -Signature: - -```typescript -export declare function child(parent: DatabaseReference, path: string): DatabaseReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| parent | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The parent location. | -| path | string | A relative path from this location to the desired child location. | - -Returns: - -[DatabaseReference](./database.databasereference.md#databasereference_interface) - -The specified child location. - -## push() - -Generates a new child location using a unique key and returns its `Reference`. - -This is the most common pattern for adding data to a collection of items. - -If you provide a value to `push()`, the value is written to the generated location. If you don't pass a value, nothing is written to the database and the child remains empty (but you can use the `Reference` elsewhere). - -The unique keys generated by `push()` are ordered by the current time, so the resulting list of items is chronologically sorted. The keys are also designed to be unguessable (they contain 72 random bits of entropy). - -See [Append to a list of data](https://firebase.google.com/docs/database/web/lists-of-data#append_to_a_list_of_data). See [The 2^120 Ways to Ensure Unique Identifiers](https://firebase.googleblog.com/2015/02/the-2120-ways-to-ensure-unique_68.html). - -Signature: - -```typescript -export declare function push(parent: DatabaseReference, value?: unknown): ThenableReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| parent | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The parent location. | -| value | unknown | Optional value to be written at the generated location. | - -Returns: - -[ThenableReference](./database.thenablereference.md#thenablereference_interface) - -Combined `Promise` and `Reference`; resolves when write is complete, but can be used immediately as the `Reference` to the child location. - -## orderByChild() - -Creates a new `QueryConstraint` that orders by the specified child key. - -Queries can only order by one key at a time. Calling `orderByChild()` multiple times on the same query is an error. - -Firebase queries allow you to order your data by any child key on the fly. However, if you know in advance what your indexes will be, you can define them via the .indexOn rule in your Security Rules for better performance. See the[https://firebase.google.com/docs/database/security/indexing-data](https://firebase.google.com/docs/database/security/indexing-data) rule for more information. - -You can read more about `orderByChild()` in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). - -Signature: - -```typescript -export declare function orderByChild(path: string): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| path | string | The path to order by. | - -Returns: - -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) - -## get() - -Gets the most up-to-date result for this query. - -Signature: - -```typescript -export declare function get(query: Query): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | - -Returns: - -Promise<[DataSnapshot](./database.datasnapshot.md#datasnapshot_class)> - -A `Promise` which resolves to the resulting DataSnapshot if a value is available, or rejects if the client is unable to return a value (e.g., if the server is unreachable and there is nothing cached). - -## off() - -Detaches a callback previously attached with the corresponding `on*()` (`onValue`, `onChildAdded`) listener. Note: This is not the recommended way to remove a listener. Instead, please use the returned callback function from the respective `on*` callbacks. - -Detach a callback previously attached with `on*()`. Calling `off()` on a parent listener will not automatically remove listeners registered on child nodes, `off()` must also be called on any child listeners to remove the callback. - -If a callback is not specified, all callbacks for the specified eventType will be removed. Similarly, if no eventType is specified, all callbacks for the `Reference` will be removed. - -Individual listeners can also be removed by invoking their unsubscribe callbacks. - -Signature: - -```typescript -export declare function off(query: Query, eventType?: EventType, callback?: (snapshot: DataSnapshot, previousChildName?: string | null) => unknown): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query that the listener was registered with. | -| eventType | [EventType](./database.md#eventtype) | One of the following strings: "value", "child\_added", "child\_changed", "child\_removed", or "child\_moved." If omitted, all callbacks for the Reference will be removed. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName?: string \| null) => unknown | The callback function that was passed to on() or undefined to remove all callbacks. | - -Returns: - -void - -## onChildAdded() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onChildAdded` event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The `DataSnapshot` passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. - -Signature: - -```typescript -export declare function onChildAdded(query: Query, callback: (snapshot: DataSnapshot, previousChildName?: string | null) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName?: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | -| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onChildAdded() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onChildAdded` event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The `DataSnapshot` passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. - -Signature: - -```typescript -export declare function onChildAdded(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, options: ListenOptions): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | -| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onChildAdded() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onChildAdded` event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The `DataSnapshot` passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. - -Signature: - -```typescript -export declare function onChildAdded(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | -| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | -| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onChildChanged() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onChildChanged` event will be triggered when the data stored in a child (or any of its descendants) changes. Note that a single `child_changed` event may represent multiple changes to the child. The `DataSnapshot` passed to the callback will contain the new child contents. For ordering purposes, the callback is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. - -Signature: - -```typescript -export declare function onChildChanged(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | -| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onChildChanged() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onChildChanged` event will be triggered when the data stored in a child (or any of its descendants) changes. Note that a single `child_changed` event may represent multiple changes to the child. The `DataSnapshot` passed to the callback will contain the new child contents. For ordering purposes, the callback is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. - -Signature: - -```typescript -export declare function onChildChanged(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, options: ListenOptions): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | -| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onChildChanged() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onChildChanged` event will be triggered when the data stored in a child (or any of its descendants) changes. Note that a single `child_changed` event may represent multiple changes to the child. The `DataSnapshot` passed to the callback will contain the new child contents. For ordering purposes, the callback is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. - -Signature: - -```typescript -export declare function onChildChanged(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | -| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | -| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onChildMoved() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onChildMoved` event will be triggered when a child's sort order changes such that its position relative to its siblings changes. The `DataSnapshot` passed to the callback will be for the data of the child that has moved. It is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. - -Signature: - -```typescript -export declare function onChildMoved(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | -| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onChildMoved() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onChildMoved` event will be triggered when a child's sort order changes such that its position relative to its siblings changes. The `DataSnapshot` passed to the callback will be for the data of the child that has moved. It is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. - -Signature: - -```typescript -export declare function onChildMoved(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, options: ListenOptions): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | -| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onChildMoved() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onChildMoved` event will be triggered when a child's sort order changes such that its position relative to its siblings changes. The `DataSnapshot` passed to the callback will be for the data of the child that has moved. It is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. - -Signature: - -```typescript -export declare function onChildMoved(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | -| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | -| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onChildRemoved() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onChildRemoved` event will be triggered once every time a child is removed. The `DataSnapshot` passed into the callback will be the old data for the child that was removed. A child will get removed when either: - -- a client explicitly calls `remove()` on that child or one of its ancestors - a client calls `set(null)` on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) - -Signature: - -```typescript -export declare function onChildRemoved(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | -| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onChildRemoved() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onChildRemoved` event will be triggered once every time a child is removed. The `DataSnapshot` passed into the callback will be the old data for the child that was removed. A child will get removed when either: - -- a client explicitly calls `remove()` on that child or one of its ancestors - a client calls `set(null)` on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) - -Signature: - -```typescript -export declare function onChildRemoved(query: Query, callback: (snapshot: DataSnapshot) => unknown, options: ListenOptions): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | -| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onChildRemoved() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onChildRemoved` event will be triggered once every time a child is removed. The `DataSnapshot` passed into the callback will be the old data for the child that was removed. A child will get removed when either: - -- a client explicitly calls `remove()` on that child or one of its ancestors - a client calls `set(null)` on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) - -Signature: - -```typescript -export declare function onChildRemoved(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | -| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | -| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onValue() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onValue` event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The `DataSnapshot` passed to the callback will be for the location at which `on()` was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty `DataSnapshot` (`val()` will return `null`). - -Signature: - -```typescript -export declare function onValue(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot. | -| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onValue() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onValue` event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The `DataSnapshot` passed to the callback will be for the location at which `on()` was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty `DataSnapshot` (`val()` will return `null`). - -Signature: - -```typescript -export declare function onValue(query: Query, callback: (snapshot: DataSnapshot) => unknown, options: ListenOptions): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot. | -| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## onValue() - -Listens for data changes at a particular location. - -This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. - -An `onValue` event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The `DataSnapshot` passed to the callback will be for the location at which `on()` was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty `DataSnapshot` (`val()` will return `null`). - -Signature: - -```typescript -export declare function onValue(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The query to run. | -| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot. | -| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | -| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | - -Returns: - -[Unsubscribe](./database.md#unsubscribe) - -A function that can be invoked to remove the listener. - -## query() - -Creates a new immutable instance of `Query` that is extended to also include additional query constraints. - -Signature: - -```typescript -export declare function query(query: Query, ...queryConstraints: QueryConstraint[]): Query; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./database.query.md#query_interface) | The Query instance to use as a base for the new constraints. | -| queryConstraints | [QueryConstraint](./database.queryconstraint.md#queryconstraint_class)\[\] | The list of QueryConstraints to apply. | - -Returns: - -[Query](./database.query.md#query_interface) - -## Exceptions - -if any of the provided query constraints cannot be combined with the existing or new constraints. - -## onDisconnect() - -Returns an `OnDisconnect` object - see [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information on how to use it. - -Signature: - -```typescript -export declare function onDisconnect(ref: DatabaseReference): OnDisconnect; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The reference to add OnDisconnect triggers for. | - -Returns: - -[OnDisconnect](./database.ondisconnect.md#ondisconnect_class) - -## remove() - -Removes the data at this Database location. - -Any data at child locations will also be deleted. - -The effect of the remove will be visible immediately and the corresponding event 'value' will be triggered. Synchronization of the remove to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the onComplete callback will be called asynchronously after synchronization has finished. - -Signature: - -```typescript -export declare function remove(ref: DatabaseReference): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location to remove. | - -Returns: - -Promise<void> - -Resolves when remove on server is complete. - -## runTransaction() - -Atomically modifies the data at this location. - -Atomically modify the data at this location. Unlike a normal `set()`, which just overwrites the data regardless of its previous value, `runTransaction()` is used to modify the existing value to a new value, ensuring there are no conflicts with other clients writing to the same location at the same time. - -To accomplish this, you pass `runTransaction()` an update function which is used to transform the current value into a new value. If another client writes to the location before your new value is successfully written, your update function will be called again with the new current value, and the write will be retried. This will happen repeatedly until your write succeeds without conflict or you abort the transaction by not returning a value from your update function. - -Note: Modifying data with `set()` will cancel any pending transactions at that location, so extreme care should be taken if mixing `set()` and `runTransaction()` to update the same data. - -Note: When using transactions with Security and Firebase Rules in place, be aware that a client needs `.read` access in addition to `.write` access in order to perform a transaction. This is because the client-side nature of transactions requires the client to read the data in order to transactionally update it. - -Signature: - -```typescript -export declare function runTransaction(ref: DatabaseReference, transactionUpdate: (currentData: any) => unknown, options?: TransactionOptions): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location to atomically modify. | -| transactionUpdate | (currentData: any) => unknown | A developer-supplied function which will be passed the current data stored at this location (as a JavaScript object). The function should return the new value it would like written (as a JavaScript object). If undefined is returned (i.e. you return with no arguments) the transaction will be aborted and the data at this location will not be modified. | -| options | [TransactionOptions](./database.transactionoptions.md#transactionoptions_interface) | An options object to configure transactions. | - -Returns: - -Promise<[TransactionResult](./database.transactionresult.md#transactionresult_class)> - -A `Promise` that can optionally be used instead of the `onComplete` callback to handle success and failure. - -## set() - -Writes data to this Database location. - -This will overwrite any data at this location and all child locations. - -The effect of the write will be visible immediately, and the corresponding events ("value", "child\_added", etc.) will be triggered. Synchronization of the data to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the `onComplete` callback will be called asynchronously after synchronization has finished. - -Passing `null` for the new value is equivalent to calling `remove()`; namely, all data at this location and all child locations will be deleted. - -`set()` will remove any priority stored at this location, so if priority is meant to be preserved, you need to use `setWithPriority()` instead. - -Note that modifying data with `set()` will cancel any pending transactions at that location, so extreme care should be taken if mixing `set()` and `transaction()` to modify the same data. - -A single `set()` will generate a single "value" event at the location where the `set()` was performed. - -Signature: - -```typescript -export declare function set(ref: DatabaseReference, value: unknown): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location to write to. | -| value | unknown | The value to be written (string, number, boolean, object, array, or null). | - -Returns: - -Promise<void> - -Resolves when write to server is complete. - -## setPriority() - -Sets a priority for the data at this Database location. - -Applications need not use priority but can order collections by ordinary properties (see [Sorting and filtering data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) ). - -Signature: - -```typescript -export declare function setPriority(ref: DatabaseReference, priority: string | number | null): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location to write to. | -| priority | string \| number \| null | The priority to be written (string, number, or null). | - -Returns: - -Promise<void> - -Resolves when write to server is complete. - -## setWithPriority() - -Writes data the Database location. Like `set()` but also specifies the priority for that data. - -Applications need not use priority but can order collections by ordinary properties (see [Sorting and filtering data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) ). - -Signature: - -```typescript -export declare function setWithPriority(ref: DatabaseReference, value: unknown, priority: string | number | null): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location to write to. | -| value | unknown | The value to be written (string, number, boolean, object, array, or null). | -| priority | string \| number \| null | The priority to be written (string, number, or null). | - -Returns: - -Promise<void> - -Resolves when write to server is complete. - -## update() - -Writes multiple values to the Database at once. - -The `values` argument contains multiple property-value pairs that will be written to the Database together. Each child property can either be a simple property (for example, "name") or a relative path (for example, "name/first") from the current location to the data to update. - -As opposed to the `set()` method, `update()` can be use to selectively update only the referenced properties at the current location (instead of replacing all the child properties at the current location). - -The effect of the write will be visible immediately, and the corresponding events ('value', 'child\_added', etc.) will be triggered. Synchronization of the data to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the `onComplete` callback will be called asynchronously after synchronization has finished. - -A single `update()` will generate a single "value" event at the location where the `update()` was performed, regardless of how many children were modified. - -Note that modifying data with `update()` will cancel any pending transactions at that location, so extreme care should be taken if mixing `update()` and `transaction()` to modify the same data. - -Passing `null` to `update()` will remove the data at this location. - -See [Introducing multi-location updates and more](https://firebase.googleblog.com/2015/09/introducing-multi-location-updates-and_86.html). - -Signature: - -```typescript -export declare function update(ref: DatabaseReference, values: object): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location to write to. | -| values | object | Object containing multiple values. | - -Returns: - -Promise<void> - -Resolves when update on server is complete. - -## endAt() - -Creates a `QueryConstraint` with the specified ending point. - -Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. - -The ending point is inclusive, so children with exactly the specified value will be included in the query. The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have a key name less than or equal to the specified key. - -You can read more about `endAt()` in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). - -Signature: - -```typescript -export declare function endAt(value: number | string | boolean | null, key?: string): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| value | number \| string \| boolean \| null | The value to end at. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | -| key | string | The child key to end at, among the children with the previously specified priority. This argument is only allowed if ordering by child, value, or priority. | - -Returns: - -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) - -## endBefore() - -Creates a `QueryConstraint` with the specified ending point (exclusive). - -Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. - -The ending point is exclusive. If only a value is provided, children with a value less than the specified value will be included in the query. If a key is specified, then children must have a value less than or equal to the specified value and a key name less than the specified key. - -Signature: - -```typescript -export declare function endBefore(value: number | string | boolean | null, key?: string): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| value | number \| string \| boolean \| null | The value to end before. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | -| key | string | The child key to end before, among the children with the previously specified priority. This argument is only allowed if ordering by child, value, or priority. | - -Returns: - -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) - -## equalTo() - -Creates a `QueryConstraint` that includes children that match the specified value. - -Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. - -The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have exactly the specified key as their key name. This can be used to filter result sets with many matches for the same value. - -You can read more about `equalTo()` in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). - -Signature: - -```typescript -export declare function equalTo(value: number | string | boolean | null, key?: string): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| value | number \| string \| boolean \| null | The value to match for. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | -| key | string | The child key to start at, among the children with the previously specified priority. This argument is only allowed if ordering by child, value, or priority. | - -Returns: - -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) - -## startAfter() - -Creates a `QueryConstraint` with the specified starting point (exclusive). - -Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. - -The starting point is exclusive. If only a value is provided, children with a value greater than the specified value will be included in the query. If a key is specified, then children must have a value greater than or equal to the specified value and a a key name greater than the specified key. - -Signature: - -```typescript -export declare function startAfter(value: number | string | boolean | null, key?: string): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| value | number \| string \| boolean \| null | The value to start after. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | -| key | string | The child key to start after. This argument is only allowed if ordering by child, value, or priority. | - -Returns: - -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) - -## startAt() - -Creates a `QueryConstraint` with the specified starting point. - -Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. - -The starting point is inclusive, so children with exactly the specified value will be included in the query. The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have a key name greater than or equal to the specified key. - -You can read more about `startAt()` in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). - -Signature: - -```typescript -export declare function startAt(value?: number | string | boolean | null, key?: string): QueryConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| value | number \| string \| boolean \| null | The value to start at. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | -| key | string | The child key to start at. This argument is only allowed if ordering by child, value, or priority. | - -Returns: - -[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) - -## EventType - -One of the following strings: "value", "child\_added", "child\_changed", "child\_removed", or "child\_moved." - -Signature: - -```typescript -export declare type EventType = 'value' | 'child_added' | 'child_changed' | 'child_moved' | 'child_removed'; -``` - -## QueryConstraintType - -Describes the different query constraints available in this SDK. - -Signature: - -```typescript -export declare type QueryConstraintType = 'endAt' | 'endBefore' | 'startAt' | 'startAfter' | 'limitToFirst' | 'limitToLast' | 'orderByChild' | 'orderByKey' | 'orderByPriority' | 'orderByValue' | 'equalTo'; -``` - -## Unsubscribe - -A callback that can invoked to remove a listener. - -Signature: - -```typescript -export declare type Unsubscribe = () => void; -``` diff --git a/docs-devsite/database.ondisconnect.md b/docs-devsite/database.ondisconnect.md deleted file mode 100644 index b7ed5075365..00000000000 --- a/docs-devsite/database.ondisconnect.md +++ /dev/null @@ -1,143 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# OnDisconnect class -The `onDisconnect` class allows you to write or clear data when your client disconnects from the Database server. These updates occur whether your client disconnects cleanly or not, so you can rely on them to clean up data even if a connection is dropped or a client crashes. - -The `onDisconnect` class is most commonly used to manage presence in applications where it is useful to detect how many clients are connected and when other clients disconnect. See [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information. - -To avoid problems when a connection is dropped before the requests can be transferred to the Database server, these functions should be called before writing any data. - -Note that `onDisconnect` operations are only triggered once. If you want an operation to occur each time a disconnect occurs, you'll need to re-establish the `onDisconnect` operations each time you reconnect. - -Signature: - -```typescript -export declare class OnDisconnect -``` - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [cancel()](./database.ondisconnect.md#ondisconnectcancel) | | Cancels all previously queued onDisconnect() set or update events for this location and all children.If a write has been queued for this location via a set() or update() at a parent location, the write at this location will be canceled, though writes to sibling locations will still occur. | -| [remove()](./database.ondisconnect.md#ondisconnectremove) | | Ensures the data at this location is deleted when the client is disconnected (due to closing the browser, navigating to a new page, or network issues). | -| [set(value)](./database.ondisconnect.md#ondisconnectset) | | Ensures the data at this location is set to the specified value when the client is disconnected (due to closing the browser, navigating to a new page, or network issues).set() is especially useful for implementing "presence" systems, where a value should be changed or cleared when a user disconnects so that they appear "offline" to other users. See [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information.Note that onDisconnect operations are only triggered once. If you want an operation to occur each time a disconnect occurs, you'll need to re-establish the onDisconnect operations each time. | -| [setWithPriority(value, priority)](./database.ondisconnect.md#ondisconnectsetwithpriority) | | Ensures the data at this location is set to the specified value and priority when the client is disconnected (due to closing the browser, navigating to a new page, or network issues). | -| [update(values)](./database.ondisconnect.md#ondisconnectupdate) | | Writes multiple values at this location when the client is disconnected (due to closing the browser, navigating to a new page, or network issues).The values argument contains multiple property-value pairs that will be written to the Database together. Each child property can either be a simple property (for example, "name") or a relative path (for example, "name/first") from the current location to the data to update.As opposed to the set() method, update() can be use to selectively update only the referenced properties at the current location (instead of replacing all the child properties at the current location). | - -## OnDisconnect.cancel() - -Cancels all previously queued `onDisconnect()` set or update events for this location and all children. - -If a write has been queued for this location via a `set()` or `update()` at a parent location, the write at this location will be canceled, though writes to sibling locations will still occur. - -Signature: - -```typescript -cancel(): Promise; -``` -Returns: - -Promise<void> - -Resolves when synchronization to the server is complete. - -## OnDisconnect.remove() - -Ensures the data at this location is deleted when the client is disconnected (due to closing the browser, navigating to a new page, or network issues). - -Signature: - -```typescript -remove(): Promise; -``` -Returns: - -Promise<void> - -Resolves when synchronization to the server is complete. - -## OnDisconnect.set() - -Ensures the data at this location is set to the specified value when the client is disconnected (due to closing the browser, navigating to a new page, or network issues). - -`set()` is especially useful for implementing "presence" systems, where a value should be changed or cleared when a user disconnects so that they appear "offline" to other users. See [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information. - -Note that `onDisconnect` operations are only triggered once. If you want an operation to occur each time a disconnect occurs, you'll need to re-establish the `onDisconnect` operations each time. - -Signature: - -```typescript -set(value: unknown): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| value | unknown | The value to be written to this location on disconnect (can be an object, array, string, number, boolean, or null). | - -Returns: - -Promise<void> - -Resolves when synchronization to the Database is complete. - -## OnDisconnect.setWithPriority() - -Ensures the data at this location is set to the specified value and priority when the client is disconnected (due to closing the browser, navigating to a new page, or network issues). - -Signature: - -```typescript -setWithPriority(value: unknown, priority: number | string | null): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| value | unknown | The value to be written to this location on disconnect (can be an object, array, string, number, boolean, or null). | -| priority | number \| string \| null | The priority to be written (string, number, or null). | - -Returns: - -Promise<void> - -Resolves when synchronization to the Database is complete. - -## OnDisconnect.update() - -Writes multiple values at this location when the client is disconnected (due to closing the browser, navigating to a new page, or network issues). - -The `values` argument contains multiple property-value pairs that will be written to the Database together. Each child property can either be a simple property (for example, "name") or a relative path (for example, "name/first") from the current location to the data to update. - -As opposed to the `set()` method, `update()` can be use to selectively update only the referenced properties at the current location (instead of replacing all the child properties at the current location). - -Signature: - -```typescript -update(values: object): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| values | object | Object containing multiple values. | - -Returns: - -Promise<void> - -Resolves when synchronization to the Database is complete. - diff --git a/docs-devsite/database.query.md b/docs-devsite/database.query.md deleted file mode 100644 index 8ef7b8f8e46..00000000000 --- a/docs-devsite/database.query.md +++ /dev/null @@ -1,108 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Query interface -A `Query` sorts and filters the data at a Database location so only a subset of the child data is included. This can be used to order a collection of data by some attribute (for example, height of dinosaurs) as well as to restrict a large list of items (for example, chat messages) down to a number suitable for synchronizing to the client. Queries are created by chaining together one or more of the filter methods defined here. - -Just as with a `DatabaseReference`, you can receive data from a `Query` by using the `on*()` methods. You will only receive events and `DataSnapshot`s for the subset of the data that matches your query. - -See [https://firebase.google.com/docs/database/web/lists-of-data\#sorting\_and\_filtering\_data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) for more information. - -Signature: - -```typescript -export declare interface Query -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [ref](./database.query.md#queryref) | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The DatabaseReference for the Query's location. | - -## Methods - -| Method | Description | -| --- | --- | -| [isEqual(other)](./database.query.md#queryisequal) | Returns whether or not the current and provided queries represent the same location, have the same query parameters, and are from the same instance of FirebaseApp.Two DatabaseReference objects are equivalent if they represent the same location and are from the same instance of FirebaseApp.Two Query objects are equivalent if they represent the same location, have the same query parameters, and are from the same instance of FirebaseApp. Equivalent queries share the same sort order, limits, and starting and ending points. | -| [toJSON()](./database.query.md#querytojson) | Returns a JSON-serializable representation of this object. | -| [toString()](./database.query.md#querytostring) | Gets the absolute URL for this location.The toString() method returns a URL that is ready to be put into a browser, curl command, or a refFromURL() call. Since all of those expect the URL to be url-encoded, toString() returns an encoded URL.Append '.json' to the returned URL when typed into a browser to download JSON-formatted data. If the location is secured (that is, not publicly readable), you will get a permission-denied error. | - -## Query.ref - -The `DatabaseReference` for the `Query`'s location. - -Signature: - -```typescript -readonly ref: DatabaseReference; -``` - -## Query.isEqual() - -Returns whether or not the current and provided queries represent the same location, have the same query parameters, and are from the same instance of `FirebaseApp`. - -Two `DatabaseReference` objects are equivalent if they represent the same location and are from the same instance of `FirebaseApp`. - -Two `Query` objects are equivalent if they represent the same location, have the same query parameters, and are from the same instance of `FirebaseApp`. Equivalent queries share the same sort order, limits, and starting and ending points. - -Signature: - -```typescript -isEqual(other: Query | null): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| other | [Query](./database.query.md#query_interface) \| null | The query to compare against. | - -Returns: - -boolean - -Whether or not the current and provided queries are equivalent. - -## Query.toJSON() - -Returns a JSON-serializable representation of this object. - -Signature: - -```typescript -toJSON(): string; -``` -Returns: - -string - -A JSON-serializable representation of this object. - -## Query.toString() - -Gets the absolute URL for this location. - -The `toString()` method returns a URL that is ready to be put into a browser, curl command, or a `refFromURL()` call. Since all of those expect the URL to be url-encoded, `toString()` returns an encoded URL. - -Append '.json' to the returned URL when typed into a browser to download JSON-formatted data. If the location is secured (that is, not publicly readable), you will get a permission-denied error. - -Signature: - -```typescript -toString(): string; -``` -Returns: - -string - -The absolute URL for this location. - diff --git a/docs-devsite/database.queryconstraint.md b/docs-devsite/database.queryconstraint.md deleted file mode 100644 index fe98c6badf3..00000000000 --- a/docs-devsite/database.queryconstraint.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryConstraint class -A `QueryConstraint` is used to narrow the set of documents returned by a Database query. `QueryConstraint`s are created by invoking [endAt()](./database.md#endat), [endBefore()](./database.md#endbefore), [startAt()](./database.md#startat), [startAfter()](./database.md#startafter), [limitToFirst()](./database.md#limittofirst), [limitToLast()](./database.md#limittolast), [orderByChild()](./database.md#orderbychild), [orderByChild()](./database.md#orderbychild), [orderByKey()](./database.md#orderbykey) , [orderByPriority()](./database.md#orderbypriority) , [orderByValue()](./database.md#orderbyvalue) or [equalTo()](./database.md#equalto) and can then be passed to [query()](./database.md#query) to create a new query instance that also contains this `QueryConstraint`. - -Signature: - -```typescript -export declare abstract class QueryConstraint -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./database.queryconstraint.md#queryconstrainttype) | | [QueryConstraintType](./database.md#queryconstrainttype) | The type of this query constraints | - -## QueryConstraint.type - -The type of this query constraints - -Signature: - -```typescript -abstract readonly type: QueryConstraintType; -``` diff --git a/docs-devsite/database.thenablereference.md b/docs-devsite/database.thenablereference.md deleted file mode 100644 index b6231d2bd03..00000000000 --- a/docs-devsite/database.thenablereference.md +++ /dev/null @@ -1,21 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ThenableReference interface -A `Promise` that can also act as a `DatabaseReference` when returned by [push()](./database.md#push). The reference is available immediately and the `Promise` resolves as the write to the backend completes. - -Signature: - -```typescript -export declare interface ThenableReference extends DatabaseReference, Pick, 'then' | 'catch'> -``` -Extends: [DatabaseReference](./database.databasereference.md#databasereference_interface), Pick<Promise<[DatabaseReference](./database.databasereference.md#databasereference_interface)>, 'then' \| 'catch'> - diff --git a/docs-devsite/database.transactionoptions.md b/docs-devsite/database.transactionoptions.md deleted file mode 100644 index 0dee85c3a99..00000000000 --- a/docs-devsite/database.transactionoptions.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# TransactionOptions interface -An options object to configure transactions. - -Signature: - -```typescript -export declare interface TransactionOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [applyLocally](./database.transactionoptions.md#transactionoptionsapplylocally) | boolean | By default, events are raised each time the transaction update function runs. So if it is run multiple times, you may see intermediate states. You can set this to false to suppress these intermediate states and instead wait until the transaction has completed before events are raised. | - -## TransactionOptions.applyLocally - -By default, events are raised each time the transaction update function runs. So if it is run multiple times, you may see intermediate states. You can set this to false to suppress these intermediate states and instead wait until the transaction has completed before events are raised. - -Signature: - -```typescript -readonly applyLocally?: boolean; -``` diff --git a/docs-devsite/database.transactionresult.md b/docs-devsite/database.transactionresult.md deleted file mode 100644 index aad84fd6a6b..00000000000 --- a/docs-devsite/database.transactionresult.md +++ /dev/null @@ -1,66 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# TransactionResult class -A type for the resolve value of [runTransaction()](./database.md#runtransaction). - -Signature: - -```typescript -export declare class TransactionResult -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [committed](./database.transactionresult.md#transactionresultcommitted) | | boolean | Whether the transaction was successfully committed. | -| [snapshot](./database.transactionresult.md#transactionresultsnapshot) | | [DataSnapshot](./database.datasnapshot.md#datasnapshot_class) | The resulting data snapshot. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [toJSON()](./database.transactionresult.md#transactionresulttojson) | | Returns a JSON-serializable representation of this object. | - -## TransactionResult.committed - -Whether the transaction was successfully committed. - -Signature: - -```typescript -readonly committed: boolean; -``` - -## TransactionResult.snapshot - -The resulting data snapshot. - -Signature: - -```typescript -readonly snapshot: DataSnapshot; -``` - -## TransactionResult.toJSON() - -Returns a JSON-serializable representation of this object. - -Signature: - -```typescript -toJSON(): object; -``` -Returns: - -object - diff --git a/docs-devsite/firestore.md b/docs-devsite/firestore.md deleted file mode 100644 index c8c647cf611..00000000000 --- a/docs-devsite/firestore.md +++ /dev/null @@ -1,19 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# firestore package -Cloud Firestore - -| Entry Point | Description | -| --- | --- | -| [/](./firestore_.md#@firebase/firestore) | | -| [/lite](./firestore_lite.md#@firebase/firestore/lite) | | - diff --git a/docs-devsite/firestore_.aggregatefield.md b/docs-devsite/firestore_.aggregatefield.md deleted file mode 100644 index 0c3957520b3..00000000000 --- a/docs-devsite/firestore_.aggregatefield.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AggregateField class -Represents an aggregation that can be performed by Firestore. - -Signature: - -```typescript -export declare class AggregateField -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_.aggregatefield.md#aggregatefieldtype) | | string | A type string to uniquely identify instances of this class. | - -## AggregateField.type - -A type string to uniquely identify instances of this class. - -Signature: - -```typescript -type: string; -``` diff --git a/docs-devsite/firestore_.aggregatequerysnapshot.md b/docs-devsite/firestore_.aggregatequerysnapshot.md deleted file mode 100644 index 1cf63b5db8b..00000000000 --- a/docs-devsite/firestore_.aggregatequerysnapshot.md +++ /dev/null @@ -1,70 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AggregateQuerySnapshot class -The results of executing an aggregation query. - -Signature: - -```typescript -export declare class AggregateQuerySnapshot -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [query](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshotquery) | | [Query](./firestore_.query.md#query_class)<unknown> | The underlying query over which the aggregations recorded in this AggregateQuerySnapshot were performed. | -| [type](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshottype) | | (not declared) | A type string to uniquely identify instances of this class. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [data()](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshotdata) | | Returns the results of the aggregations performed over the underlying query.The keys of the returned object will be the same as those of the AggregateSpec object specified to the aggregation method, and the values will be the corresponding aggregation result. | - -## AggregateQuerySnapshot.query - -The underlying query over which the aggregations recorded in this `AggregateQuerySnapshot` were performed. - -Signature: - -```typescript -readonly query: Query; -``` - -## AggregateQuerySnapshot.type - -A type string to uniquely identify instances of this class. - -Signature: - -```typescript -readonly type = "AggregateQuerySnapshot"; -``` - -## AggregateQuerySnapshot.data() - -Returns the results of the aggregations performed over the underlying query. - -The keys of the returned object will be the same as those of the `AggregateSpec` object specified to the aggregation method, and the values will be the corresponding aggregation result. - -Signature: - -```typescript -data(): AggregateSpecData; -``` -Returns: - -[AggregateSpecData](./firestore_.md#aggregatespecdata)<T> - -The results of the aggregations performed over the underlying query. - diff --git a/docs-devsite/firestore_.aggregatespec.md b/docs-devsite/firestore_.aggregatespec.md deleted file mode 100644 index be06b6941f3..00000000000 --- a/docs-devsite/firestore_.aggregatespec.md +++ /dev/null @@ -1,19 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AggregateSpec interface -A type whose property values are all `AggregateField` objects. - -Signature: - -```typescript -export declare interface AggregateSpec -``` diff --git a/docs-devsite/firestore_.bytes.md b/docs-devsite/firestore_.bytes.md deleted file mode 100644 index 411abe327c5..00000000000 --- a/docs-devsite/firestore_.bytes.md +++ /dev/null @@ -1,138 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Bytes class -An immutable object representing an array of bytes. - -Signature: - -```typescript -export declare class Bytes -``` - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [fromBase64String(base64)](./firestore_.bytes.md#bytesfrombase64string) | static | Creates a new Bytes object from the given Base64 string, converting it to bytes. | -| [fromUint8Array(array)](./firestore_.bytes.md#bytesfromuint8array) | static | Creates a new Bytes object from the given Uint8Array. | -| [isEqual(other)](./firestore_.bytes.md#bytesisequal) | | Returns true if this Bytes object is equal to the provided one. | -| [toBase64()](./firestore_.bytes.md#bytestobase64) | | Returns the underlying bytes as a Base64-encoded string. | -| [toString()](./firestore_.bytes.md#bytestostring) | | Returns a string representation of the Bytes object. | -| [toUint8Array()](./firestore_.bytes.md#bytestouint8array) | | Returns the underlying bytes in a new Uint8Array. | - -## Bytes.fromBase64String() - -Creates a new `Bytes` object from the given Base64 string, converting it to bytes. - -Signature: - -```typescript -static fromBase64String(base64: string): Bytes; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| base64 | string | The Base64 string used to create the Bytes object. | - -Returns: - -[Bytes](./firestore_.bytes.md#bytes_class) - -## Bytes.fromUint8Array() - -Creates a new `Bytes` object from the given Uint8Array. - -Signature: - -```typescript -static fromUint8Array(array: Uint8Array): Bytes; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| array | Uint8Array | The Uint8Array used to create the Bytes object. | - -Returns: - -[Bytes](./firestore_.bytes.md#bytes_class) - -## Bytes.isEqual() - -Returns true if this `Bytes` object is equal to the provided one. - -Signature: - -```typescript -isEqual(other: Bytes): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| other | [Bytes](./firestore_.bytes.md#bytes_class) | The Bytes object to compare against. | - -Returns: - -boolean - -true if this `Bytes` object is equal to the provided one. - -## Bytes.toBase64() - -Returns the underlying bytes as a Base64-encoded string. - -Signature: - -```typescript -toBase64(): string; -``` -Returns: - -string - -The Base64-encoded string created from the `Bytes` object. - -## Bytes.toString() - -Returns a string representation of the `Bytes` object. - -Signature: - -```typescript -toString(): string; -``` -Returns: - -string - -A string representation of the `Bytes` object. - -## Bytes.toUint8Array() - -Returns the underlying bytes in a new `Uint8Array`. - -Signature: - -```typescript -toUint8Array(): Uint8Array; -``` -Returns: - -Uint8Array - -The Uint8Array created from the `Bytes` object. - diff --git a/docs-devsite/firestore_.collectionreference.md b/docs-devsite/firestore_.collectionreference.md deleted file mode 100644 index 56c81c6b245..00000000000 --- a/docs-devsite/firestore_.collectionreference.md +++ /dev/null @@ -1,121 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# CollectionReference class -A `CollectionReference` object can be used for adding documents, getting document references, and querying for documents (using [query()](./firestore_.md#query)). - -Signature: - -```typescript -export declare class CollectionReference extends Query -``` -Extends: [Query](./firestore_.query.md#query_class)<T> - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [id](./firestore_.collectionreference.md#collectionreferenceid) | | string | The collection's identifier. | -| [parent](./firestore_.collectionreference.md#collectionreferenceparent) | | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> \| null | A reference to the containing DocumentReference if this is a subcollection. If this isn't a subcollection, the reference is null. | -| [path](./firestore_.collectionreference.md#collectionreferencepath) | | string | A string representing the path of the referenced collection (relative to the root of the database). | -| [type](./firestore_.collectionreference.md#collectionreferencetype) | | (not declared) | The type of this Firestore reference. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [withConverter(converter)](./firestore_.collectionreference.md#collectionreferencewithconverter) | | Applies a custom data converter to this CollectionReference, allowing you to use your own custom model objects with Firestore. When you call [addDoc()](./firestore_.md#adddoc) with the returned CollectionReference instance, the provided converter will convert between Firestore data and your custom type U. | -| [withConverter(converter)](./firestore_.collectionreference.md#collectionreferencewithconverter) | | Removes the current converter. | - -## CollectionReference.id - -The collection's identifier. - -Signature: - -```typescript -get id(): string; -``` - -## CollectionReference.parent - -A reference to the containing `DocumentReference` if this is a subcollection. If this isn't a subcollection, the reference is null. - -Signature: - -```typescript -get parent(): DocumentReference | null; -``` - -## CollectionReference.path - -A string representing the path of the referenced collection (relative to the root of the database). - -Signature: - -```typescript -get path(): string; -``` - -## CollectionReference.type - -The type of this Firestore reference. - -Signature: - -```typescript -readonly type = "collection"; -``` - -## CollectionReference.withConverter() - -Applies a custom data converter to this `CollectionReference`, allowing you to use your own custom model objects with Firestore. When you call [addDoc()](./firestore_.md#adddoc) with the returned `CollectionReference` instance, the provided converter will convert between Firestore data and your custom type `U`. - -Signature: - -```typescript -withConverter(converter: FirestoreDataConverter): CollectionReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| converter | [FirestoreDataConverter](./firestore_.firestoredataconverter.md#firestoredataconverter_interface)<U> | Converts objects to and from Firestore. | - -Returns: - -[CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<U> - -A `CollectionReference` that uses the provided converter. - -## CollectionReference.withConverter() - -Removes the current converter. - -Signature: - -```typescript -withConverter(converter: null): CollectionReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| converter | null | null removes the current converter. | - -Returns: - -[CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> - -A `CollectionReference` that does not use a converter. - diff --git a/docs-devsite/firestore_.documentchange.md b/docs-devsite/firestore_.documentchange.md deleted file mode 100644 index afef795956d..00000000000 --- a/docs-devsite/firestore_.documentchange.md +++ /dev/null @@ -1,68 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# DocumentChange interface -A `DocumentChange` represents a change to the documents matching a query. It contains the document affected and the type of change that occurred. - -Signature: - -```typescript -export declare interface DocumentChange -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [doc](./firestore_.documentchange.md#documentchangedoc) | [QueryDocumentSnapshot](./firestore_.querydocumentsnapshot.md#querydocumentsnapshot_class)<T> | The document affected by this change. | -| [newIndex](./firestore_.documentchange.md#documentchangenewindex) | number | The index of the changed document in the result set immediately after this DocumentChange (i.e. supposing that all prior DocumentChange objects and the current DocumentChange object have been applied). Is -1 for 'removed' events. | -| [oldIndex](./firestore_.documentchange.md#documentchangeoldindex) | number | The index of the changed document in the result set immediately prior to this DocumentChange (i.e. supposing that all prior DocumentChange objects have been applied). Is -1 for 'added' events. | -| [type](./firestore_.documentchange.md#documentchangetype) | [DocumentChangeType](./firestore_.md#documentchangetype) | The type of change ('added', 'modified', or 'removed'). | - -## DocumentChange.doc - -The document affected by this change. - -Signature: - -```typescript -readonly doc: QueryDocumentSnapshot; -``` - -## DocumentChange.newIndex - -The index of the changed document in the result set immediately after this `DocumentChange` (i.e. supposing that all prior `DocumentChange` objects and the current `DocumentChange` object have been applied). Is -1 for 'removed' events. - -Signature: - -```typescript -readonly newIndex: number; -``` - -## DocumentChange.oldIndex - -The index of the changed document in the result set immediately prior to this `DocumentChange` (i.e. supposing that all prior `DocumentChange` objects have been applied). Is `-1` for 'added' events. - -Signature: - -```typescript -readonly oldIndex: number; -``` - -## DocumentChange.type - -The type of change ('added', 'modified', or 'removed'). - -Signature: - -```typescript -readonly type: DocumentChangeType; -``` diff --git a/docs-devsite/firestore_.documentdata.md b/docs-devsite/firestore_.documentdata.md deleted file mode 100644 index 09b5eb64b48..00000000000 --- a/docs-devsite/firestore_.documentdata.md +++ /dev/null @@ -1,19 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# DocumentData interface -Document data (for use with [setDoc()](./firestore_lite.md#setdoc)) consists of fields mapped to values. - -Signature: - -```typescript -export declare interface DocumentData -``` diff --git a/docs-devsite/firestore_.documentreference.md b/docs-devsite/firestore_.documentreference.md deleted file mode 100644 index 16dff93b9c8..00000000000 --- a/docs-devsite/firestore_.documentreference.md +++ /dev/null @@ -1,142 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# DocumentReference class -A `DocumentReference` refers to a document location in a Firestore database and can be used to write, read, or listen to the location. The document at the referenced location may or may not exist. - -Signature: - -```typescript -export declare class DocumentReference -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [converter](./firestore_.documentreference.md#documentreferenceconverter) | | [FirestoreDataConverter](./firestore_.firestoredataconverter.md#firestoredataconverter_interface)<T> \| null | If provided, the FirestoreDataConverter associated with this instance. | -| [firestore](./firestore_.documentreference.md#documentreferencefirestore) | | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance the document is in. This is useful for performing transactions, for example. | -| [id](./firestore_.documentreference.md#documentreferenceid) | | string | The document's identifier within its collection. | -| [parent](./firestore_.documentreference.md#documentreferenceparent) | | [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | The collection this DocumentReference belongs to. | -| [path](./firestore_.documentreference.md#documentreferencepath) | | string | A string representing the path of the referenced document (relative to the root of the database). | -| [type](./firestore_.documentreference.md#documentreferencetype) | | (not declared) | The type of this Firestore reference. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [withConverter(converter)](./firestore_.documentreference.md#documentreferencewithconverter) | | Applies a custom data converter to this DocumentReference, allowing you to use your own custom model objects with Firestore. When you call [setDoc()](./firestore_lite.md#setdoc), [getDoc()](./firestore_lite.md#getdoc), etc. with the returned DocumentReference instance, the provided converter will convert between Firestore data and your custom type U. | -| [withConverter(converter)](./firestore_.documentreference.md#documentreferencewithconverter) | | Removes the current converter. | - -## DocumentReference.converter - -If provided, the `FirestoreDataConverter` associated with this instance. - -Signature: - -```typescript -readonly converter: FirestoreDataConverter | null; -``` - -## DocumentReference.firestore - -The [Firestore](./firestore_.firestore.md#firestore_class) instance the document is in. This is useful for performing transactions, for example. - -Signature: - -```typescript -readonly firestore: Firestore; -``` - -## DocumentReference.id - -The document's identifier within its collection. - -Signature: - -```typescript -get id(): string; -``` - -## DocumentReference.parent - -The collection this `DocumentReference` belongs to. - -Signature: - -```typescript -get parent(): CollectionReference; -``` - -## DocumentReference.path - -A string representing the path of the referenced document (relative to the root of the database). - -Signature: - -```typescript -get path(): string; -``` - -## DocumentReference.type - -The type of this Firestore reference. - -Signature: - -```typescript -readonly type = "document"; -``` - -## DocumentReference.withConverter() - -Applies a custom data converter to this `DocumentReference`, allowing you to use your own custom model objects with Firestore. When you call [setDoc()](./firestore_lite.md#setdoc), [getDoc()](./firestore_lite.md#getdoc), etc. with the returned `DocumentReference` instance, the provided converter will convert between Firestore data and your custom type `U`. - -Signature: - -```typescript -withConverter(converter: FirestoreDataConverter): DocumentReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| converter | [FirestoreDataConverter](./firestore_.firestoredataconverter.md#firestoredataconverter_interface)<U> | Converts objects to and from Firestore. | - -Returns: - -[DocumentReference](./firestore_.documentreference.md#documentreference_class)<U> - -A `DocumentReference` that uses the provided converter. - -## DocumentReference.withConverter() - -Removes the current converter. - -Signature: - -```typescript -withConverter(converter: null): DocumentReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| converter | null | null removes the current converter. | - -Returns: - -[DocumentReference](./firestore_.documentreference.md#documentreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> - -A `DocumentReference` that does not use a converter. - diff --git a/docs-devsite/firestore_.documentsnapshot.md b/docs-devsite/firestore_.documentsnapshot.md deleted file mode 100644 index 3ac2ec7dcb2..00000000000 --- a/docs-devsite/firestore_.documentsnapshot.md +++ /dev/null @@ -1,146 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# DocumentSnapshot class -A `DocumentSnapshot` contains data read from a document in your Firestore database. The data can be extracted with `.data()` or `.get()` to get a specific field. - -For a `DocumentSnapshot` that points to a non-existing document, any data access will return 'undefined'. You can use the `exists()` method to explicitly verify a document's existence. - -Signature: - -```typescript -export declare class DocumentSnapshot -``` - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)()](./firestore_.documentsnapshot.md#documentsnapshotconstructor) | | Constructs a new instance of the DocumentSnapshot class | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [id](./firestore_.documentsnapshot.md#documentsnapshotid) | | string | Property of the DocumentSnapshot that provides the document's ID. | -| [metadata](./firestore_.documentsnapshot.md#documentsnapshotmetadata) | | [SnapshotMetadata](./firestore_.snapshotmetadata.md#snapshotmetadata_class) | Metadata about the DocumentSnapshot, including information about its source and local modifications. | -| [ref](./firestore_.documentsnapshot.md#documentsnapshotref) | | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | The DocumentReference for the document included in the DocumentSnapshot. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [data(options)](./firestore_.documentsnapshot.md#documentsnapshotdata) | | Retrieves all fields in the document as an Object. Returns undefined if the document doesn't exist.By default, serverTimestamp() values that have not yet been set to their final value will be returned as null. You can override this by passing an options object. | -| [exists()](./firestore_.documentsnapshot.md#documentsnapshotexists) | | Returns whether or not the data exists. True if the document exists. | -| [get(fieldPath, options)](./firestore_.documentsnapshot.md#documentsnapshotget) | | Retrieves the field specified by fieldPath. Returns undefined if the document or field doesn't exist.By default, a serverTimestamp() that has not yet been set to its final value will be returned as null. You can override this by passing an options object. | - -## DocumentSnapshot.(constructor) - -Constructs a new instance of the `DocumentSnapshot` class - -Signature: - -```typescript -protected constructor(); -``` - -## DocumentSnapshot.id - -Property of the `DocumentSnapshot` that provides the document's ID. - -Signature: - -```typescript -get id(): string; -``` - -## DocumentSnapshot.metadata - -Metadata about the `DocumentSnapshot`, including information about its source and local modifications. - -Signature: - -```typescript -readonly metadata: SnapshotMetadata; -``` - -## DocumentSnapshot.ref - -The `DocumentReference` for the document included in the `DocumentSnapshot`. - -Signature: - -```typescript -get ref(): DocumentReference; -``` - -## DocumentSnapshot.data() - -Retrieves all fields in the document as an `Object`. Returns `undefined` if the document doesn't exist. - -By default, `serverTimestamp()` values that have not yet been set to their final value will be returned as `null`. You can override this by passing an options object. - -Signature: - -```typescript -data(options?: SnapshotOptions): T | undefined; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| options | [SnapshotOptions](./firestore_.snapshotoptions.md#snapshotoptions_interface) | An options object to configure how data is retrieved from the snapshot (for example the desired behavior for server timestamps that have not yet been set to their final value). | - -Returns: - -T \| undefined - -An `Object` containing all fields in the document or `undefined` if the document doesn't exist. - -## DocumentSnapshot.exists() - -Returns whether or not the data exists. True if the document exists. - -Signature: - -```typescript -exists(): this is QueryDocumentSnapshot; -``` -Returns: - -this is [QueryDocumentSnapshot](./firestore_.querydocumentsnapshot.md#querydocumentsnapshot_class)<T> - -## DocumentSnapshot.get() - -Retrieves the field specified by `fieldPath`. Returns `undefined` if the document or field doesn't exist. - -By default, a `serverTimestamp()` that has not yet been set to its final value will be returned as `null`. You can override this by passing an options object. - -Signature: - -```typescript -get(fieldPath: string | FieldPath, options?: SnapshotOptions): any; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldPath | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The path (for example 'foo' or 'foo.bar') to a specific field. | -| options | [SnapshotOptions](./firestore_.snapshotoptions.md#snapshotoptions_interface) | An options object to configure how the field is retrieved from the snapshot (for example the desired behavior for server timestamps that have not yet been set to their final value). | - -Returns: - -any - -The data at the specified field location or undefined if no such field exists in the document. - diff --git a/docs-devsite/firestore_.fieldpath.md b/docs-devsite/firestore_.fieldpath.md deleted file mode 100644 index 8a9143f02a8..00000000000 --- a/docs-devsite/firestore_.fieldpath.md +++ /dev/null @@ -1,72 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FieldPath class -A `FieldPath` refers to a field in a document. The path may consist of a single field name (referring to a top-level field in the document), or a list of field names (referring to a nested field in the document). - -Create a `FieldPath` by providing field names. If more than one field name is provided, the path will point to a nested field in a document. - -Signature: - -```typescript -export declare class FieldPath -``` - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(fieldNames)](./firestore_.fieldpath.md#fieldpathconstructor) | | Creates a FieldPath from the provided field names. If more than one field name is provided, the path will point to a nested field in a document. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [isEqual(other)](./firestore_.fieldpath.md#fieldpathisequal) | | Returns true if this FieldPath is equal to the provided one. | - -## FieldPath.(constructor) - -Creates a `FieldPath` from the provided field names. If more than one field name is provided, the path will point to a nested field in a document. - -Signature: - -```typescript -constructor(...fieldNames: string[]); -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldNames | string\[\] | A list of field names. | - -## FieldPath.isEqual() - -Returns true if this `FieldPath` is equal to the provided one. - -Signature: - -```typescript -isEqual(other: FieldPath): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| other | [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The FieldPath to compare against. | - -Returns: - -boolean - -true if this `FieldPath` is equal to the provided one. - diff --git a/docs-devsite/firestore_.fieldvalue.md b/docs-devsite/firestore_.fieldvalue.md deleted file mode 100644 index 62c034583d6..00000000000 --- a/docs-devsite/firestore_.fieldvalue.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FieldValue class -Sentinel values that can be used when writing document fields with `set()` or `update()`. - -Signature: - -```typescript -export declare abstract class FieldValue -``` - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [isEqual(other)](./firestore_.fieldvalue.md#fieldvalueisequal) | | Compares FieldValues for equality. | - -## FieldValue.isEqual() - -Compares `FieldValue`s for equality. - -Signature: - -```typescript -abstract isEqual(other: FieldValue): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| other | [FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) | | - -Returns: - -boolean - diff --git a/docs-devsite/firestore_.firestore.md b/docs-devsite/firestore_.firestore.md deleted file mode 100644 index 01267d5b2d3..00000000000 --- a/docs-devsite/firestore_.firestore.md +++ /dev/null @@ -1,68 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Firestore class -The Cloud Firestore service interface. - -Do not call this constructor directly. Instead, use [getFirestore()](./firestore_.md#getfirestore). - -Signature: - -```typescript -export declare class Firestore -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [app](./firestore_.firestore.md#firestoreapp) | | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this Firestore service instance. | -| [type](./firestore_.firestore.md#firestoretype) | | 'firestore-lite' \| 'firestore' | Whether it's a [Firestore](./firestore_.firestore.md#firestore_class) or Firestore Lite instance. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [toJSON()](./firestore_.firestore.md#firestoretojson) | | Returns a JSON-serializable representation of this Firestore instance. | - -## Firestore.app - -The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this `Firestore` service instance. - -Signature: - -```typescript -get app(): FirebaseApp; -``` - -## Firestore.type - -Whether it's a [Firestore](./firestore_.firestore.md#firestore_class) or Firestore Lite instance. - -Signature: - -```typescript -type: 'firestore-lite' | 'firestore'; -``` - -## Firestore.toJSON() - -Returns a JSON-serializable representation of this `Firestore` instance. - -Signature: - -```typescript -toJSON(): object; -``` -Returns: - -object - diff --git a/docs-devsite/firestore_.firestoredataconverter.md b/docs-devsite/firestore_.firestoredataconverter.md deleted file mode 100644 index f7d80ac4a13..00000000000 --- a/docs-devsite/firestore_.firestoredataconverter.md +++ /dev/null @@ -1,134 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FirestoreDataConverter interface -Converter used by `withConverter()` to transform user objects of type `T` into Firestore data. - -Using the converter allows you to specify generic type arguments when storing and retrieving objects from Firestore. - -Signature: - -```typescript -export declare interface FirestoreDataConverter -``` - -## Methods - -| Method | Description | -| --- | --- | -| [fromFirestore(snapshot, options)](./firestore_.firestoredataconverter.md#firestoredataconverterfromfirestore) | Called by the Firestore SDK to convert Firestore data into an object of type T. You can access your data by calling: snapshot.data(options). | -| [toFirestore(modelObject)](./firestore_.firestoredataconverter.md#firestoredataconvertertofirestore) | Called by the Firestore SDK to convert a custom model object of type T into a plain JavaScript object (suitable for writing directly to the Firestore database). To use set() with merge and mergeFields, toFirestore() must be defined with PartialWithFieldValue<T>.The WithFieldValue<T> type extends T to also allow FieldValues such as [deleteField()](./firestore_.md#deletefield) to be used as property values. | -| [toFirestore(modelObject, options)](./firestore_.firestoredataconverter.md#firestoredataconvertertofirestore) | Called by the Firestore SDK to convert a custom model object of type T into a plain JavaScript object (suitable for writing directly to the Firestore database). Used with [setDoc()](./firestore_.md#setdoc), and with merge:true or mergeFields.The PartialWithFieldValue<T> type extends Partial<T> to allow FieldValues such as [arrayUnion()](./firestore_.md#arrayunion) to be used as property values. It also supports nested Partial by allowing nested fields to be omitted. | - -## FirestoreDataConverter.fromFirestore() - -Called by the Firestore SDK to convert Firestore data into an object of type T. You can access your data by calling: `snapshot.data(options)`. - -Signature: - -```typescript -fromFirestore(snapshot: QueryDocumentSnapshot, options?: SnapshotOptions): T; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| snapshot | [QueryDocumentSnapshot](./firestore_.querydocumentsnapshot.md#querydocumentsnapshot_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> | A QueryDocumentSnapshot containing your data and metadata. | -| options | [SnapshotOptions](./firestore_.snapshotoptions.md#snapshotoptions_interface) | The SnapshotOptions from the initial call to data(). | - -Returns: - -T - -## FirestoreDataConverter.toFirestore() - -Called by the Firestore SDK to convert a custom model object of type `T` into a plain JavaScript object (suitable for writing directly to the Firestore database). To use `set()` with `merge` and `mergeFields`, `toFirestore()` must be defined with `PartialWithFieldValue`. - -The `WithFieldValue` type extends `T` to also allow FieldValues such as [deleteField()](./firestore_.md#deletefield) to be used as property values. - -Signature: - -```typescript -toFirestore(modelObject: WithFieldValue): DocumentData; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| modelObject | [WithFieldValue](./firestore_.md#withfieldvalue)<T> | | - -Returns: - -[DocumentData](./firestore_.documentdata.md#documentdata_interface) - -## FirestoreDataConverter.toFirestore() - -Called by the Firestore SDK to convert a custom model object of type `T` into a plain JavaScript object (suitable for writing directly to the Firestore database). Used with [setDoc()](./firestore_.md#setdoc), and with `merge:true` or `mergeFields`. - -The `PartialWithFieldValue` type extends `Partial` to allow FieldValues such as [arrayUnion()](./firestore_.md#arrayunion) to be used as property values. It also supports nested `Partial` by allowing nested fields to be omitted. - -Signature: - -```typescript -toFirestore(modelObject: PartialWithFieldValue, options: SetOptions): DocumentData; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| modelObject | [PartialWithFieldValue](./firestore_.md#partialwithfieldvalue)<T> | | -| options | [SetOptions](./firestore_.md#setoptions) | | - -Returns: - -[DocumentData](./firestore_.documentdata.md#documentdata_interface) - -### Example - - -```typescript -class Post { - constructor(readonly title: string, readonly author: string) {} - - toString(): string { - return this.title + ', by ' + this.author; - } -} - -const postConverter = { - toFirestore(post: WithFieldValue): DocumentData { - return {title: post.title, author: post.author}; - }, - fromFirestore( - snapshot: QueryDocumentSnapshot, - options: SnapshotOptions - ): Post { - const data = snapshot.data(options)!; - return new Post(data.title, data.author); - } -}; - -const postSnap = await firebase.firestore() - .collection('posts') - .withConverter(postConverter) - .doc().get(); -const post = postSnap.data(); -if (post !== undefined) { - post.title; // string - post.toString(); // Should be defined - post.someNonExistentProperty; // TS error -} - -``` - diff --git a/docs-devsite/firestore_.firestoreerror.md b/docs-devsite/firestore_.firestoreerror.md deleted file mode 100644 index c16cf39541e..00000000000 --- a/docs-devsite/firestore_.firestoreerror.md +++ /dev/null @@ -1,58 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FirestoreError class -An error returned by a Firestore operation. - -Signature: - -```typescript -export declare class FirestoreError extends FirebaseError -``` -Extends: [FirebaseError](./util.firebaseerror.md#firebaseerror_class) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [code](./firestore_.firestoreerror.md#firestoreerrorcode) | | [FirestoreErrorCode](./firestore_.md#firestoreerrorcode) | The backend error code associated with this error. | -| [message](./firestore_.firestoreerror.md#firestoreerrormessage) | | string | A custom error description. | -| [stack](./firestore_.firestoreerror.md#firestoreerrorstack) | | string | The stack of the error. | - -## FirestoreError.code - -The backend error code associated with this error. - -Signature: - -```typescript -readonly code: FirestoreErrorCode; -``` - -## FirestoreError.message - -A custom error description. - -Signature: - -```typescript -readonly message: string; -``` - -## FirestoreError.stack - -The stack of the error. - -Signature: - -```typescript -readonly stack?: string; -``` diff --git a/docs-devsite/firestore_.firestoresettings.md b/docs-devsite/firestore_.firestoresettings.md deleted file mode 100644 index 96fe454cb77..00000000000 --- a/docs-devsite/firestore_.firestoresettings.md +++ /dev/null @@ -1,96 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FirestoreSettings interface -Specifies custom configurations for your Cloud Firestore instance. You must set these before invoking any other methods. - -Signature: - -```typescript -export declare interface FirestoreSettings -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [cacheSizeBytes](./firestore_.firestoresettings.md#firestoresettingscachesizebytes) | number | An approximate cache size threshold for the on-disk data. If the cache grows beyond this size, Firestore will start removing data that hasn't been recently used. The size is not a guarantee that the cache will stay below that size, only that if the cache exceeds the given size, cleanup will be attempted.The default value is 40 MB. The threshold must be set to at least 1 MB, and can be set to CACHE_SIZE_UNLIMITED to disable garbage collection. | -| [experimentalAutoDetectLongPolling](./firestore_.firestoresettings.md#firestoresettingsexperimentalautodetectlongpolling) | boolean | Configures the SDK's underlying transport (WebChannel) to automatically detect if long-polling should be used. This is very similar to experimentalForceLongPolling, but only uses long-polling if required.This setting will likely be enabled by default in future releases and cannot be combined with experimentalForceLongPolling. | -| [experimentalForceLongPolling](./firestore_.firestoresettings.md#firestoresettingsexperimentalforcelongpolling) | boolean | Forces the SDK’s underlying network transport (WebChannel) to use long-polling. Each response from the backend will be closed immediately after the backend sends data (by default responses are kept open in case the backend has more data to send). This avoids incompatibility issues with certain proxies, antivirus software, etc. that incorrectly buffer traffic indefinitely. Use of this option will cause some performance degradation though.This setting cannot be used with experimentalAutoDetectLongPolling and may be removed in a future release. If you find yourself using it to work around a specific network reliability issue, please tell us about it in https://github.com/firebase/firebase-js-sdk/issues/1674. | -| [host](./firestore_.firestoresettings.md#firestoresettingshost) | string | The hostname to connect to. | -| [ignoreUndefinedProperties](./firestore_.firestoresettings.md#firestoresettingsignoreundefinedproperties) | boolean | Whether to skip nested properties that are set to undefined during object serialization. If set to true, these properties are skipped and not written to Firestore. If set to false or omitted, the SDK throws an exception when it encounters properties of type undefined. | -| [ssl](./firestore_.firestoresettings.md#firestoresettingsssl) | boolean | Whether to use SSL when connecting. | - -## FirestoreSettings.cacheSizeBytes - -An approximate cache size threshold for the on-disk data. If the cache grows beyond this size, Firestore will start removing data that hasn't been recently used. The size is not a guarantee that the cache will stay below that size, only that if the cache exceeds the given size, cleanup will be attempted. - -The default value is 40 MB. The threshold must be set to at least 1 MB, and can be set to `CACHE_SIZE_UNLIMITED` to disable garbage collection. - -Signature: - -```typescript -cacheSizeBytes?: number; -``` - -## FirestoreSettings.experimentalAutoDetectLongPolling - -Configures the SDK's underlying transport (WebChannel) to automatically detect if long-polling should be used. This is very similar to `experimentalForceLongPolling`, but only uses long-polling if required. - -This setting will likely be enabled by default in future releases and cannot be combined with `experimentalForceLongPolling`. - -Signature: - -```typescript -experimentalAutoDetectLongPolling?: boolean; -``` - -## FirestoreSettings.experimentalForceLongPolling - -Forces the SDK’s underlying network transport (WebChannel) to use long-polling. Each response from the backend will be closed immediately after the backend sends data (by default responses are kept open in case the backend has more data to send). This avoids incompatibility issues with certain proxies, antivirus software, etc. that incorrectly buffer traffic indefinitely. Use of this option will cause some performance degradation though. - -This setting cannot be used with `experimentalAutoDetectLongPolling` and may be removed in a future release. If you find yourself using it to work around a specific network reliability issue, please tell us about it in https://github.com/firebase/firebase-js-sdk/issues/1674. - -Signature: - -```typescript -experimentalForceLongPolling?: boolean; -``` - -## FirestoreSettings.host - -The hostname to connect to. - -Signature: - -```typescript -host?: string; -``` - -## FirestoreSettings.ignoreUndefinedProperties - -Whether to skip nested properties that are set to `undefined` during object serialization. If set to `true`, these properties are skipped and not written to Firestore. If set to `false` or omitted, the SDK throws an exception when it encounters properties of type `undefined`. - -Signature: - -```typescript -ignoreUndefinedProperties?: boolean; -``` - -## FirestoreSettings.ssl - -Whether to use SSL when connecting. - -Signature: - -```typescript -ssl?: boolean; -``` diff --git a/docs-devsite/firestore_.geopoint.md b/docs-devsite/firestore_.geopoint.md deleted file mode 100644 index d2fd1bd7392..00000000000 --- a/docs-devsite/firestore_.geopoint.md +++ /dev/null @@ -1,117 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# GeoPoint class -An immutable object representing a geographic location in Firestore. The location is represented as latitude/longitude pair. - -Latitude values are in the range of \[-90, 90\]. Longitude values are in the range of \[-180, 180\]. - -Signature: - -```typescript -export declare class GeoPoint -``` - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(latitude, longitude)](./firestore_.geopoint.md#geopointconstructor) | | Creates a new immutable GeoPoint object with the provided latitude and longitude values. | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [latitude](./firestore_.geopoint.md#geopointlatitude) | | number | The latitude of this GeoPoint instance. | -| [longitude](./firestore_.geopoint.md#geopointlongitude) | | number | The longitude of this GeoPoint instance. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [isEqual(other)](./firestore_.geopoint.md#geopointisequal) | | Returns true if this GeoPoint is equal to the provided one. | -| [toJSON()](./firestore_.geopoint.md#geopointtojson) | | Returns a JSON-serializable representation of this GeoPoint. | - -## GeoPoint.(constructor) - -Creates a new immutable `GeoPoint` object with the provided latitude and longitude values. - -Signature: - -```typescript -constructor(latitude: number, longitude: number); -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| latitude | number | The latitude as number between -90 and 90. | -| longitude | number | The longitude as number between -180 and 180. | - -## GeoPoint.latitude - -The latitude of this `GeoPoint` instance. - -Signature: - -```typescript -get latitude(): number; -``` - -## GeoPoint.longitude - -The longitude of this `GeoPoint` instance. - -Signature: - -```typescript -get longitude(): number; -``` - -## GeoPoint.isEqual() - -Returns true if this `GeoPoint` is equal to the provided one. - -Signature: - -```typescript -isEqual(other: GeoPoint): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| other | [GeoPoint](./firestore_.geopoint.md#geopoint_class) | The GeoPoint to compare against. | - -Returns: - -boolean - -true if this `GeoPoint` is equal to the provided one. - -## GeoPoint.toJSON() - -Returns a JSON-serializable representation of this GeoPoint. - -Signature: - -```typescript -toJSON(): { - latitude: number; - longitude: number; - }; -``` -Returns: - -{ latitude: number; longitude: number; } - diff --git a/docs-devsite/firestore_.index.md b/docs-devsite/firestore_.index.md deleted file mode 100644 index 3ea216d6798..00000000000 --- a/docs-devsite/firestore_.index.md +++ /dev/null @@ -1,55 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Index interface -> 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. -> - -The SDK definition of a Firestore index. - -Signature: - -```typescript -export declare interface Index -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [collectionGroup](./firestore_.index.md#indexcollectiongroup) | string | (BETA) The ID of the collection to index. | -| [fields](./firestore_.index.md#indexfields) | [IndexField](./firestore_.indexfield.md#indexfield_interface)\[\] | (BETA) A list of fields to index. | - -## Index.collectionGroup - -> 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. -> - -The ID of the collection to index. - -Signature: - -```typescript -readonly collectionGroup: string; -``` - -## Index.fields - -> 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. -> - -A list of fields to index. - -Signature: - -```typescript -readonly fields?: IndexField[]; -``` diff --git a/docs-devsite/firestore_.indexconfiguration.md b/docs-devsite/firestore_.indexconfiguration.md deleted file mode 100644 index 8a0592e7ed6..00000000000 --- a/docs-devsite/firestore_.indexconfiguration.md +++ /dev/null @@ -1,43 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# IndexConfiguration interface -> 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. -> - -A list of Firestore indexes to speed up local query execution. - -See [JSON Format](https://firebase.google.com/docs/reference/firestore/indexes/#json_format) for a description of the format of the index definition. - -Signature: - -```typescript -export declare interface IndexConfiguration -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [indexes](./firestore_.indexconfiguration.md#indexconfigurationindexes) | [Index](./firestore_.index.md#index_interface)\[\] | (BETA) A list of all Firestore indexes. | - -## IndexConfiguration.indexes - -> 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. -> - -A list of all Firestore indexes. - -Signature: - -```typescript -readonly indexes?: Index[]; -``` diff --git a/docs-devsite/firestore_.indexfield.md b/docs-devsite/firestore_.indexfield.md deleted file mode 100644 index 278e2f63ce8..00000000000 --- a/docs-devsite/firestore_.indexfield.md +++ /dev/null @@ -1,73 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# IndexField interface -> 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. -> - -A single field element in an index configuration. - -Signature: - -```typescript -export declare interface IndexField -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [arrayConfig](./firestore_.indexfield.md#indexfieldarrayconfig) | 'CONTAINS' | (BETA) What type of array index to create. Set to CONTAINS for array-contains and array-contains-any indexes.Only one of arrayConfig or order should be set; | -| [fieldPath](./firestore_.indexfield.md#indexfieldfieldpath) | string | (BETA) The field path to index. | -| [order](./firestore_.indexfield.md#indexfieldorder) | 'ASCENDING' \| 'DESCENDING' | (BETA) What type of array index to create. Set to ASCENDING or 'DESCENDING for ==, !=, <=, <=, in and not-in\` filters.Only one of arrayConfig or order should be set. | - -## IndexField.arrayConfig - -> 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. -> - -What type of array index to create. Set to `CONTAINS` for `array-contains` and `array-contains-any` indexes. - -Only one of `arrayConfig` or `order` should be set; - -Signature: - -```typescript -readonly arrayConfig?: 'CONTAINS'; -``` - -## IndexField.fieldPath - -> 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. -> - -The field path to index. - -Signature: - -```typescript -readonly fieldPath: string; -``` - -## IndexField.order - -> 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. -> - -What type of array index to create. Set to `ASCENDING` or 'DESCENDING` for `==`, `!=`, `<=`, `<=`, `in` and `not-in\` filters. - -Only one of `arrayConfig` or `order` should be set. - -Signature: - -```typescript -readonly order?: 'ASCENDING' | 'DESCENDING'; -``` diff --git a/docs-devsite/firestore_.loadbundletask.md b/docs-devsite/firestore_.loadbundletask.md deleted file mode 100644 index 8b446d5d6e1..00000000000 --- a/docs-devsite/firestore_.loadbundletask.md +++ /dev/null @@ -1,94 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# LoadBundleTask class -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`. - -Signature: - -```typescript -export declare class LoadBundleTask implements PromiseLike -``` -Implements: PromiseLike<[LoadBundleTaskProgress](./firestore_.loadbundletaskprogress.md#loadbundletaskprogress_interface)> - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [catch(onRejected)](./firestore_.loadbundletask.md#loadbundletaskcatch) | | Implements the Promise<LoadBundleTaskProgress>.catch interface. | -| [onProgress(next, error, complete)](./firestore_.loadbundletask.md#loadbundletaskonprogress) | | Registers functions to listen to bundle loading progress events. | -| [then(onFulfilled, onRejected)](./firestore_.loadbundletask.md#loadbundletaskthen) | | Implements the Promise<LoadBundleTaskProgress>.then interface. | - -## LoadBundleTask.catch() - -Implements the `Promise.catch` interface. - -Signature: - -```typescript -catch(onRejected: (a: Error) => R | PromiseLike): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| onRejected | (a: Error) => R \| PromiseLike<R> | Called when an error occurs during bundle loading. | - -Returns: - -Promise<R \| [LoadBundleTaskProgress](./firestore_.loadbundletaskprogress.md#loadbundletaskprogress_interface)> - -## LoadBundleTask.onProgress() - -Registers functions to listen to bundle loading progress events. - -Signature: - -```typescript -onProgress(next?: (progress: LoadBundleTaskProgress) => unknown, error?: (err: Error) => unknown, complete?: () => void): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| next | (progress: [LoadBundleTaskProgress](./firestore_.loadbundletaskprogress.md#loadbundletaskprogress_interface)) => unknown | Called when there is a progress update from bundle loading. Typically next calls occur each time a Firestore document is loaded from the bundle. | -| error | (err: Error) => unknown | Called when an error occurs during bundle loading. The task aborts after reporting the error, and there should be no more updates after this. | -| complete | () => void | Called when the loading task is complete. | - -Returns: - -void - -## LoadBundleTask.then() - -Implements the `Promise.then` interface. - -Signature: - -```typescript -then(onFulfilled?: (a: LoadBundleTaskProgress) => T | PromiseLike, onRejected?: (a: Error) => R | PromiseLike): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| onFulfilled | (a: [LoadBundleTaskProgress](./firestore_.loadbundletaskprogress.md#loadbundletaskprogress_interface)) => T \| PromiseLike<T> | Called on the completion of the loading task with a final LoadBundleTaskProgress update. The update will always have its taskState set to "Success". | -| onRejected | (a: Error) => R \| PromiseLike<R> | Called when an error occurs during bundle loading. | - -Returns: - -Promise<T \| R> - diff --git a/docs-devsite/firestore_.loadbundletaskprogress.md b/docs-devsite/firestore_.loadbundletaskprogress.md deleted file mode 100644 index 98124754928..00000000000 --- a/docs-devsite/firestore_.loadbundletaskprogress.md +++ /dev/null @@ -1,79 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# LoadBundleTaskProgress interface -Represents a progress update or a final state from loading bundles. - -Signature: - -```typescript -export declare interface LoadBundleTaskProgress -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [bytesLoaded](./firestore_.loadbundletaskprogress.md#loadbundletaskprogressbytesloaded) | number | How many bytes have been loaded. | -| [documentsLoaded](./firestore_.loadbundletaskprogress.md#loadbundletaskprogressdocumentsloaded) | number | How many documents have been loaded. | -| [taskState](./firestore_.loadbundletaskprogress.md#loadbundletaskprogresstaskstate) | [TaskState](./firestore_.md#taskstate) | Current task state. | -| [totalBytes](./firestore_.loadbundletaskprogress.md#loadbundletaskprogresstotalbytes) | number | How many bytes are in the bundle being loaded. | -| [totalDocuments](./firestore_.loadbundletaskprogress.md#loadbundletaskprogresstotaldocuments) | number | How many documents are in the bundle being loaded. | - -## LoadBundleTaskProgress.bytesLoaded - -How many bytes have been loaded. - -Signature: - -```typescript -bytesLoaded: number; -``` - -## LoadBundleTaskProgress.documentsLoaded - -How many documents have been loaded. - -Signature: - -```typescript -documentsLoaded: number; -``` - -## LoadBundleTaskProgress.taskState - -Current task state. - -Signature: - -```typescript -taskState: TaskState; -``` - -## LoadBundleTaskProgress.totalBytes - -How many bytes are in the bundle being loaded. - -Signature: - -```typescript -totalBytes: number; -``` - -## LoadBundleTaskProgress.totalDocuments - -How many documents are in the bundle being loaded. - -Signature: - -```typescript -totalDocuments: number; -``` diff --git a/docs-devsite/firestore_.md b/docs-devsite/firestore_.md deleted file mode 100644 index 4a5c2dd49b2..00000000000 --- a/docs-devsite/firestore_.md +++ /dev/null @@ -1,2134 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# @firebase/firestore - -## Functions - -| Function | Description | -| --- | --- | -| 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. | -| [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. | -| [collection(firestore, path, pathSegments)](./firestore_.md#collection) | Gets a CollectionReference instance that refers to the collection at the specified absolute path. | -| [collectionGroup(firestore, collectionId)](./firestore_.md#collectiongroup) | Creates and returns a new Query instance that includes all documents in the database that are contained in a collection or subcollection with the given collectionId. | -| [connectFirestoreEmulator(firestore, host, port, options)](./firestore_.md#connectfirestoreemulator) | Modify this instance to communicate with the Cloud Firestore emulator.Note: This must be called before this instance has been used to do any operations. | -| [disableNetwork(firestore)](./firestore_.md#disablenetwork) | Disables network usage for this instance. It can be re-enabled via [enableNetwork()](./firestore_.md#enablenetwork). While the network is disabled, any snapshot listeners, getDoc() or getDocs() calls will return results from cache, and any write operations will be queued until the network is restored. | -| [doc(firestore, path, pathSegments)](./firestore_.md#doc) | Gets a DocumentReference instance that refers to the document at the specified absolute path. | -| [enableIndexedDbPersistence(firestore, persistenceSettings)](./firestore_.md#enableindexeddbpersistence) | Attempts to enable persistent storage, if possible.Must be called before any other functions (other than [initializeFirestore()](./firestore_.md#initializefirestore), [getFirestore()](./firestore_.md#getfirestore) or [clearIndexedDbPersistence()](./firestore_.md#clearindexeddbpersistence).If this fails, enableIndexedDbPersistence() will reject the promise it returns. Note that even after this failure, the [Firestore](./firestore_.firestore.md#firestore_class) instance will remain usable, however offline persistence will be disabled.There are several reasons why this can fail, which can be identified by the code on the error.\* failed-precondition: The app is already open in another browser tab. \* unimplemented: The browser is incompatible with the offline persistence implementation. | -| [enableMultiTabIndexedDbPersistence(firestore)](./firestore_.md#enablemultitabindexeddbpersistence) | Attempts to enable multi-tab persistent storage, if possible. If enabled across all tabs, all operations share access to local persistence, including shared execution of queries and latency-compensated local document updates across all connected instances.If this fails, enableMultiTabIndexedDbPersistence() will reject the promise it returns. Note that even after this failure, the [Firestore](./firestore_.firestore.md#firestore_class) instance will remain usable, however offline persistence will be disabled.There are several reasons why this can fail, which can be identified by the code on the error.\* failed-precondition: The app is already open in another browser tab and multi-tab is not enabled. \* unimplemented: The browser is incompatible with the offline persistence implementation. | -| [enableNetwork(firestore)](./firestore_.md#enablenetwork) | Re-enables use of the network for this [Firestore](./firestore_.firestore.md#firestore_class) instance after a prior call to [disableNetwork()](./firestore_.md#disablenetwork). | -| [loadBundle(firestore, bundleData)](./firestore_.md#loadbundle) | Loads a Firestore bundle into the local cache. | -| [namedQuery(firestore, name)](./firestore_.md#namedquery) | Reads a Firestore [Query](./firestore_.query.md#query_class) 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](./firestore_.query.md#query_class) by name. | -| [onSnapshotsInSync(firestore, observer)](./firestore_.md#onsnapshotsinsync) | Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners.NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use SnapshotMetadata in the individual listeners to determine if a snapshot is from the cache or the server. | -| [onSnapshotsInSync(firestore, onSync)](./firestore_.md#onsnapshotsinsync) | Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners.NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use SnapshotMetadata in the individual listeners to determine if a snapshot is from the cache or the server. | -| [runTransaction(firestore, updateFunction, options)](./firestore_.md#runtransaction) | Executes the given updateFunction and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, Cloud Firestore retries the updateFunction. If it fails to commit after 5 attempts, the transaction fails.The maximum number of writes allowed in a single transaction is 500. | -| [setIndexConfiguration(firestore, configuration)](./firestore_.md#setindexconfiguration) | (BETA) Configures indexing for local query execution. Any previous index configuration is overridden. The Promise resolves once the index configuration has been persisted.The index entries themselves are created asynchronously. You can continue to use queries that require indexing even if the indices are not yet available. Query execution will automatically start using the index once the index entries have been written.Indexes are only supported with IndexedDb persistence. Invoke either enableIndexedDbPersistence() or enableMultiTabIndexedDbPersistence() before setting an index configuration. If IndexedDb is not enabled, any index configuration is ignored. | -| [setIndexConfiguration(firestore, json)](./firestore_.md#setindexconfiguration) | (BETA) Configures indexing for local query execution. Any previous index configuration is overridden. The Promise resolves once the index configuration has been persisted.The index entries themselves are created asynchronously. You can continue to use queries that require indexing even if the indices are not yet available. Query execution will automatically start using the index once the index entries have been written.Indexes are only supported with IndexedDb persistence. Invoke either enableIndexedDbPersistence() or enableMultiTabIndexedDbPersistence() before setting an index configuration. If IndexedDb is not enabled, any index configuration is ignored.The method accepts the JSON format exported by the Firebase CLI (firebase firestore:indexes). If the JSON format is invalid, this method throws an error. | -| [terminate(firestore)](./firestore_.md#terminate) | Terminates the provided [Firestore](./firestore_.firestore.md#firestore_class) instance.After calling terminate() only the clearIndexedDbPersistence() function may be used. Any other function will throw a FirestoreError.To restart after termination, create a new instance of FirebaseFirestore with [getFirestore()](./firestore_.md#getfirestore).Termination does not cancel any pending writes, and any promises that are awaiting a response from the server will not be resolved. If you have persistence enabled, the next time you start this instance, it will resume sending these writes to the server.Note: Under normal circumstances, calling terminate() is not required. This function is useful only when you want to force this instance to release all of its resources or in combination with clearIndexedDbPersistence() to ensure that all local state is destroyed between test runs. | -| [waitForPendingWrites(firestore)](./firestore_.md#waitforpendingwrites) | Waits until all currently pending writes for the active user have been acknowledged by the backend.The returned promise resolves immediately if there are no outstanding writes. Otherwise, the promise waits for all previously issued writes (including those written in a previous app session), but it does not wait for writes that were added after the function is called. If you want to wait for additional writes, call waitForPendingWrites() again.Any outstanding waitForPendingWrites() promises are rejected during user changes. | -| [writeBatch(firestore)](./firestore_.md#writebatch) | Creates a write batch, used for performing multiple writes as a single atomic operation. The maximum number of writes allowed in a single [WriteBatch](./firestore_.writebatch.md#writebatch_class) is 500.Unlike transactions, write batches are persisted offline and therefore are preferable when you don't need to condition your writes on read data. | -| function() | -| [deleteField()](./firestore_.md#deletefield) | Returns a sentinel for use with [updateDoc()](./firestore_lite.md#updatedoc) or [setDoc()](./firestore_lite.md#setdoc) with {merge: true} to mark a field for deletion. | -| [documentId()](./firestore_.md#documentid) | Returns a special sentinel FieldPath to refer to the ID of a document. It can be used in queries to sort or filter by the document ID. | -| [getFirestore()](./firestore_.md#getfirestore) | Returns the existing default [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. | -| [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(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. | -| function(fieldPath...) | -| [orderBy(fieldPath, directionStr)](./firestore_.md#orderby) | Creates a [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class) that sorts the query result by the specified field, optionally in descending order instead of ascending.Note: Documents that do not contain the specified field will not be present in the query result. | -| [where(fieldPath, opStr, value)](./firestore_.md#where) | Creates a [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) that enforces that documents must contain the specified field and that the value should satisfy the relation constraint provided. | -| function(fieldValues...) | -| [endAt(fieldValues)](./firestore_.md#endat) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | -| [endBefore(fieldValues)](./firestore_.md#endbefore) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | -| [startAfter(fieldValues)](./firestore_.md#startafter) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | -| [startAt(fieldValues)](./firestore_.md#startat) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | -| function(left...) | -| [aggregateQuerySnapshotEqual(left, right)](./firestore_.md#aggregatequerysnapshotequal) | Compares two AggregateQuerySnapshot instances for equality.Two AggregateQuerySnapshot instances are considered "equal" if they have underlying queries that compare equal, and the same data. | -| [queryEqual(left, right)](./firestore_.md#queryequal) | Returns true if the provided queries point to the same collection and apply the same constraints. | -| [refEqual(left, right)](./firestore_.md#refequal) | Returns true if the provided references are equal. | -| [snapshotEqual(left, right)](./firestore_.md#snapshotequal) | Returns true if the provided snapshots are equal. | -| function(limit...) | -| [limit(limit)](./firestore_.md#limit) | Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the first matching documents. | -| [limitToLast(limit)](./firestore_.md#limittolast) | Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the last matching documents.You must specify at least one orderBy clause for limitToLast queries, otherwise an exception will be thrown during execution. | -| function(logLevel...) | -| [setLogLevel(logLevel)](./firestore_.md#setloglevel) | Sets the verbosity of Cloud Firestore logs (debug, error, or silent). | -| function(n...) | -| [increment(n)](./firestore_.md#increment) | 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 increment the field's current value by the given value.If either the operand or the current field value uses floating point precision, all arithmetic follows IEEE 754 semantics. If both values are integers, values outside of JavaScript's safe number range (Number.MIN_SAFE_INTEGER to Number.MAX_SAFE_INTEGER) are also subject to precision loss. Furthermore, once processed by the Firestore backend, all integer operations are capped between -2^63 and 2^63-1.If the current field value is not of type number, or if the field does not yet exist, the transformation sets the field to the given value. | -| function(query...) | -| [getCountFromServer(query)](./firestore_.md#getcountfromserver) | Calculates the number of documents in the result set of the given query, without actually downloading the documents.Using this function to count the documents is efficient because only the final count, not the documents' data, is downloaded. This function can even count the documents if the result set would be prohibitively large to download entirely (e.g. thousands of documents).The result received from the server is presented, unaltered, without considering any local state. That is, documents in the local cache are not taken into consideration, neither are local modifications not yet synchronized with the server. Previously-downloaded results, if any, are not used: every request using this source necessarily involves a round trip to the server. | -| [getDocs(query)](./firestore_.md#getdocs) | Executes the query and returns the results as a QuerySnapshot.Note: getDocs() attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. To specify this behavior, invoke [getDocsFromCache()](./firestore_.md#getdocsfromcache) or [getDocsFromServer()](./firestore_.md#getdocsfromserver). | -| [getDocsFromCache(query)](./firestore_.md#getdocsfromcache) | Executes the query and returns the results as a QuerySnapshot from cache. Returns an empty result set if no documents matching the query are currently cached. | -| [getDocsFromServer(query)](./firestore_.md#getdocsfromserver) | Executes the query and returns the results as a QuerySnapshot from the server. Returns an error if the network is not available. | -| [onSnapshot(query, observer)](./firestore_.md#onsnapshot) | Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | -| [onSnapshot(query, options, observer)](./firestore_.md#onsnapshot) | Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | -| [onSnapshot(query, onNext, onError, onCompletion)](./firestore_.md#onsnapshot) | Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | -| [onSnapshot(query, options, onNext, onError, onCompletion)](./firestore_.md#onsnapshot) | Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | -| [query(query, queryConstraints)](./firestore_.md#query) | Creates a new immutable instance of [Query](./firestore_.query.md#query_class) that is extended to also include additional query constraints. | -| function(reference...) | -| [addDoc(reference, data)](./firestore_.md#adddoc) | Add a new document to specified CollectionReference with the given data, assigning it a document ID automatically. | -| [collection(reference, path, pathSegments)](./firestore_.md#collection) | Gets a CollectionReference instance that refers to a subcollection of reference at the the specified relative path. | -| [collection(reference, path, pathSegments)](./firestore_.md#collection) | Gets a CollectionReference instance that refers to a subcollection of reference at the the specified relative path. | -| [deleteDoc(reference)](./firestore_.md#deletedoc) | Deletes the document referred to by the specified DocumentReference. | -| [doc(reference, path, pathSegments)](./firestore_.md#doc) | Gets a DocumentReference instance that refers to a document within reference at the specified relative path. If no path is specified, an automatically-generated unique ID will be used for the returned DocumentReference. | -| [doc(reference, path, pathSegments)](./firestore_.md#doc) | Gets a DocumentReference instance that refers to a document within reference at the specified relative path. | -| [getDoc(reference)](./firestore_.md#getdoc) | Reads the document referred to by this DocumentReference.Note: getDoc() attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. To specify this behavior, invoke [getDocFromCache()](./firestore_.md#getdocfromcache) or [getDocFromServer()](./firestore_.md#getdocfromserver). | -| [getDocFromCache(reference)](./firestore_.md#getdocfromcache) | Reads the document referred to by this DocumentReference from cache. Returns an error if the document is not currently cached. | -| [getDocFromServer(reference)](./firestore_.md#getdocfromserver) | Reads the document referred to by this DocumentReference from the server. Returns an error if the network is not available. | -| [onSnapshot(reference, observer)](./firestore_.md#onsnapshot) | Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | -| [onSnapshot(reference, options, observer)](./firestore_.md#onsnapshot) | Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | -| [onSnapshot(reference, onNext, onError, onCompletion)](./firestore_.md#onsnapshot) | Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | -| [onSnapshot(reference, options, onNext, onError, onCompletion)](./firestore_.md#onsnapshot) | Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | -| [setDoc(reference, data)](./firestore_.md#setdoc) | Writes to the document referred to by this DocumentReference. If the document does not yet exist, it will be created. | -| [setDoc(reference, data, options)](./firestore_.md#setdoc) | Writes to the document referred to by the specified DocumentReference. If the document does not yet exist, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document. | -| [updateDoc(reference, data)](./firestore_.md#updatedoc) | Updates fields in the document referred to by the specified DocumentReference. The update will fail if applied to a document that does not exist. | -| [updateDoc(reference, field, value, moreFieldsAndValues)](./firestore_.md#updatedoc) | Updates fields in the document referred to by the specified DocumentReference The update will fail if applied to a document that does not exist.Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects. | -| function(snapshot...) | -| [endAt(snapshot)](./firestore_.md#endat) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided document (inclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | -| [endBefore(snapshot)](./firestore_.md#endbefore) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | -| [startAfter(snapshot)](./firestore_.md#startafter) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | -| [startAt(snapshot)](./firestore_.md#startat) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of this query. | - -## Classes - -| Class | Description | -| --- | --- | -| [AggregateField](./firestore_.aggregatefield.md#aggregatefield_class) | Represents an aggregation that can be performed by Firestore. | -| [AggregateQuerySnapshot](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshot_class) | The results of executing an aggregation query. | -| [Bytes](./firestore_.bytes.md#bytes_class) | An immutable object representing an array of bytes. | -| [CollectionReference](./firestore_.collectionreference.md#collectionreference_class) | A CollectionReference object can be used for adding documents, getting document references, and querying for documents (using [query()](./firestore_.md#query)). | -| [DocumentReference](./firestore_.documentreference.md#documentreference_class) | A DocumentReference refers to a document location in a Firestore database and can be used to write, read, or listen to the location. The document at the referenced location may or may not exist. | -| [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class) | A DocumentSnapshot contains data read from a document in your Firestore database. The data can be extracted with .data() or .get(<field>) to get a specific field.For a DocumentSnapshot that points to a non-existing document, any data access will return 'undefined'. You can use the exists() method to explicitly verify a document's existence. | -| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | A FieldPath refers to a field in a document. The path may consist of a single field name (referring to a top-level field in the document), or a list of field names (referring to a nested field in the document).Create a FieldPath by providing field names. If more than one field name is provided, the path will point to a nested field in a document. | -| [FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) | Sentinel values that can be used when writing document fields with set() or update(). | -| [Firestore](./firestore_.firestore.md#firestore_class) | The Cloud Firestore service interface.Do not call this constructor directly. Instead, use [getFirestore()](./firestore_.md#getfirestore). | -| [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class) | An error returned by a Firestore operation. | -| [GeoPoint](./firestore_.geopoint.md#geopoint_class) | An immutable object representing a geographic location in Firestore. The location is represented as latitude/longitude pair.Latitude values are in the range of \[-90, 90\]. Longitude values are in the range of \[-180, 180\]. | -| [LoadBundleTask](./firestore_.loadbundletask.md#loadbundletask_class) | 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>. | -| [Query](./firestore_.query.md#query_class) | A Query refers to a query which you can read or listen to. You can also construct refined Query objects by adding filters and ordering. | -| [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) | A QueryConstraint is used to narrow the set of documents returned by a Firestore query. QueryConstraints are created by invoking [where()](./firestore_.md#where), [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit), [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryConstraint. | -| [QueryDocumentSnapshot](./firestore_.querydocumentsnapshot.md#querydocumentsnapshot_class) | A QueryDocumentSnapshot contains data read from a document in your Firestore database as part of a query. The document is guaranteed to exist and its data can be extracted with .data() or .get(<field>) to get a specific field.A QueryDocumentSnapshot offers the same API surface as a DocumentSnapshot. Since query results contain only existing documents, the exists property will always be true and data() will never return 'undefined'. | -| [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) | A QueryEndAtConstraint is used to exclude documents from the end of a result set returned by a Firestore query. QueryEndAtConstraints are created by invoking [endAt()](./firestore_.md#endat) or [endBefore()](./firestore_.md#endbefore) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryEndAtConstraint. | -| [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) | A QueryFieldFilterConstraint is used to narrow the set of documents returned by a Firestore query by filtering on one or more document fields. QueryFieldFilterConstraints are created by invoking [where()](./firestore_.md#where) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryFieldFilterConstraint. | -| [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) | A QueryLimitConstraint is used to limit the number of documents returned by a Firestore query. QueryLimitConstraints are created by invoking [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryLimitConstraint. | -| [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class) | A QueryOrderByConstraint is used to sort the set of documents returned by a Firestore query. QueryOrderByConstraints are created by invoking [orderBy()](./firestore_.md#orderby) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryOrderByConstraint.Note: Documents that do not contain the orderBy field will not be present in the query result. | -| [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class) | A QuerySnapshot contains zero or more DocumentSnapshot objects representing the results of a query. The documents can be accessed as an array via the docs property or enumerated using the forEach method. The number of documents can be determined via the empty and size properties. | -| [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) | A QueryStartAtConstraint is used to exclude documents from the start of a result set returned by a Firestore query. QueryStartAtConstraints are created by invoking [startAt()](./firestore_.md#startat) or [startAfter()](./firestore_.md#startafter) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryStartAtConstraint. | -| [SnapshotMetadata](./firestore_.snapshotmetadata.md#snapshotmetadata_class) | Metadata about a snapshot, describing the state of the snapshot. | -| [Timestamp](./firestore_.timestamp.md#timestamp_class) | A Timestamp represents a point in time independent of any time zone or calendar, represented as seconds and fractions of seconds at nanosecond resolution in UTC Epoch time.It is encoded using the Proleptic Gregorian Calendar which extends the Gregorian calendar backwards to year one. It is encoded assuming all minutes are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.For examples and further specifications, refer to the [Timestamp definition](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto). | -| [Transaction](./firestore_.transaction.md#transaction_class) | A reference to a transaction.The Transaction object passed to a transaction's updateFunction provides the methods to read and write data within the transaction context. See [runTransaction()](./firestore_.md#runtransaction). | -| [WriteBatch](./firestore_.writebatch.md#writebatch_class) | A write batch, used to perform multiple writes as a single atomic unit.A WriteBatch object can be acquired by calling [writeBatch()](./firestore_.md#writebatch). It provides methods for adding writes to the write batch. None of the writes will be committed (or visible locally) until [WriteBatch.commit()](./firestore_.writebatch.md#writebatchcommit) is called. | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [AggregateSpec](./firestore_.aggregatespec.md#aggregatespec_interface) | A type whose property values are all AggregateField objects. | -| [DocumentChange](./firestore_.documentchange.md#documentchange_interface) | A DocumentChange represents a change to the documents matching a query. It contains the document affected and the type of change that occurred. | -| [DocumentData](./firestore_.documentdata.md#documentdata_interface) | Document data (for use with [setDoc()](./firestore_lite.md#setdoc)) consists of fields mapped to values. | -| [FirestoreDataConverter](./firestore_.firestoredataconverter.md#firestoredataconverter_interface) | Converter used by withConverter() to transform user objects of type T into Firestore data.Using the converter allows you to specify generic type arguments when storing and retrieving objects from Firestore. | -| [FirestoreSettings](./firestore_.firestoresettings.md#firestoresettings_interface) | Specifies custom configurations for your Cloud Firestore instance. You must set these before invoking any other methods. | -| [Index](./firestore_.index.md#index_interface) | (BETA) The SDK definition of a Firestore index. | -| [IndexConfiguration](./firestore_.indexconfiguration.md#indexconfiguration_interface) | (BETA) A list of Firestore indexes to speed up local query execution.See [JSON Format](https://firebase.google.com/docs/reference/firestore/indexes/#json_format) for a description of the format of the index definition. | -| [IndexField](./firestore_.indexfield.md#indexfield_interface) | (BETA) A single field element in an index configuration. | -| [LoadBundleTaskProgress](./firestore_.loadbundletaskprogress.md#loadbundletaskprogress_interface) | Represents a progress update or a final state from loading bundles. | -| [PersistenceSettings](./firestore_.persistencesettings.md#persistencesettings_interface) | Settings that can be passed to enableIndexedDbPersistence() to configure Firestore persistence. | -| [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | An options object that can be passed to [onSnapshot()](./firestore_.md#onsnapshot) and [QuerySnapshot.docChanges()](./firestore_.querysnapshot.md#querysnapshotdocchanges) to control which types of changes to include in the result set. | -| [SnapshotOptions](./firestore_.snapshotoptions.md#snapshotoptions_interface) | Options that configure how data is retrieved from a DocumentSnapshot (for example the desired behavior for server timestamps that have not yet been set to their final value). | -| [TransactionOptions](./firestore_.transactionoptions.md#transactionoptions_interface) | Options to customize transaction behavior. | -| [Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) | A function returned by onSnapshot() that removes the listener when invoked. | - -## Variables - -| Variable | Description | -| --- | --- | -| [CACHE\_SIZE\_UNLIMITED](./firestore_.md#cache_size_unlimited) | Constant used to indicate the LRU garbage collection should be disabled. Set this value as the cacheSizeBytes on the settings passed to the [Firestore](./firestore_.firestore.md#firestore_class) instance. | - -## Type Aliases - -| Type Alias | Description | -| --- | --- | -| [AddPrefixToKeys](./firestore_.md#addprefixtokeys) | Returns a new map where every key is prefixed with the outer key appended to a dot. | -| [AggregateFieldType](./firestore_.md#aggregatefieldtype) | The union of all AggregateField types that are supported by Firestore. | -| [AggregateSpecData](./firestore_.md#aggregatespecdata) | A type whose keys are taken from an AggregateSpec, and whose values are the result of the aggregation performed by the corresponding AggregateField from the input AggregateSpec. | -| [ChildUpdateFields](./firestore_.md#childupdatefields) | Helper for calculating the nested fields for a given type T1. This is needed to distribute union types such as undefined | {...} (happens for optional props) or {a: A} | {b: B}.In this use case, V is used to distribute the union types of T[K] on Record, since T[K] is evaluated as an expression and not distributed.See https://www.typescriptlang.org/docs/handbook/advanced-types.html\#distributive-conditional-types | -| [DocumentChangeType](./firestore_.md#documentchangetype) | The type of a DocumentChange may be 'added', 'removed', or 'modified'. | -| [FirestoreErrorCode](./firestore_.md#firestoreerrorcode) | The set of Firestore status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.mdPossible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (e.g. an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation. | -| [NestedUpdateFields](./firestore_.md#nestedupdatefields) | For each field (e.g. 'bar'), find all nested keys (e.g. {'bar.baz': T1, 'bar.qux': T2}). Intersect them together to make a single map containing all possible keys that are all marked as optional | -| [OrderByDirection](./firestore_.md#orderbydirection) | The direction of a [orderBy()](./firestore_.md#orderby) clause is specified as 'desc' or 'asc' (descending or ascending). | -| [PartialWithFieldValue](./firestore_.md#partialwithfieldvalue) | Similar to Typescript's Partial<T>, but allows nested fields to be omitted and FieldValues to be passed in as property values. | -| [Primitive](./firestore_.md#primitive) | Primitive types. | -| [QueryConstraintType](./firestore_.md#queryconstrainttype) | Describes the different query constraints available in this SDK. | -| [QueryNonFilterConstraint](./firestore_.md#querynonfilterconstraint) | QueryNonFilterConstraint is a helper union type that represents QueryConstraints which are used to narrow or order the set of documents, but that do not explicitly filter on a document field. QueryNonFilterConstraints are created by invoking [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains the QueryConstraint. | -| [SetOptions](./firestore_.md#setoptions) | An options object that configures the behavior of [setDoc()](./firestore_lite.md#setdoc), and calls. These calls can be configured to perform granular merges instead of overwriting the target documents in their entirety by providing a SetOptions with merge: true. | -| [TaskState](./firestore_.md#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. | -| [UnionToIntersection](./firestore_.md#uniontointersection) | Given a union type U = T1 | T2 | ..., returns an intersected type (T1 & T2 & ...).Uses distributive conditional types and inference from conditional types. This works because multiple candidates for the same type variable in contra-variant positions causes an intersection type to be inferred. https://www.typescriptlang.org/docs/handbook/advanced-types.html\#type-inference-in-conditional-types https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection-type | -| [UpdateData](./firestore_.md#updatedata) | Update data (for use with [updateDoc()](./firestore_.md#updatedoc)) that consists of field paths (e.g. 'foo' or 'foo.baz') mapped to values. Fields that contain dots reference nested fields within the document. FieldValues can be passed in as property values. | -| [WhereFilterOp](./firestore_.md#wherefilterop) | Filter conditions in a [where()](./firestore_.md#where) clause are specified using the strings '&lt;', '&lt;=', '==', '!=', '&gt;=', '&gt;', 'array-contains', 'in', 'array-contains-any', and 'not-in'. | -| [WithFieldValue](./firestore_.md#withfieldvalue) | Allows FieldValues to be passed in as a property value while maintaining type safety. | - -## 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. - -Signature: - -```typescript -export declare function getFirestore(app: FirebaseApp): Firestore; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance that the returned [Firestore](./firestore_.firestore.md#firestore_class) instance is associated with. | - -Returns: - -[Firestore](./firestore_.firestore.md#firestore_class) - -The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. - -## 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). - -Signature: - -```typescript -export declare function initializeFirestore(app: FirebaseApp, settings: FirestoreSettings, databaseId?: string): Firestore; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) with which the [Firestore](./firestore_.firestore.md#firestore_class) instance will be associated. | -| settings | [FirestoreSettings](./firestore_.firestoresettings.md#firestoresettings_interface) | A settings object to configure the [Firestore](./firestore_.firestore.md#firestore_class) instance. | -| databaseId | string | The name of database. | - -Returns: - -[Firestore](./firestore_.firestore.md#firestore_class) - -A newly initialized [Firestore](./firestore_.firestore.md#firestore_class) instance. - -## 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. - -Signature: - -```typescript -export declare function clearIndexedDbPersistence(firestore: Firestore): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to clear persistence for. | - -Returns: - -Promise<void> - -A `Promise` that is resolved when the persistent storage is cleared. Otherwise, the promise is rejected with an error. - -## collection() - -Gets a `CollectionReference` instance that refers to the collection at the specified absolute path. - -Signature: - -```typescript -export declare function collection(firestore: Firestore, path: string, ...pathSegments: string[]): CollectionReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | A reference to the root Firestore instance. | -| path | string | A slash-separated path to a collection. | -| pathSegments | string\[\] | Additional path segments to apply relative to the first argument. | - -Returns: - -[CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> - -The `CollectionReference` instance. - -## Exceptions - -If the final path has an even number of segments and does not point to a collection. - -## collectionGroup() - -Creates and returns a new `Query` instance that includes all documents in the database that are contained in a collection or subcollection with the given `collectionId`. - -Signature: - -```typescript -export declare function collectionGroup(firestore: Firestore, collectionId: string): Query; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | A reference to the root Firestore instance. | -| collectionId | string | Identifies the collections to query over. Every collection or subcollection with this ID as the last segment of its path will be included. Cannot contain a slash. | - -Returns: - -[Query](./firestore_.query.md#query_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> - -The created `Query`. - -## connectFirestoreEmulator() - -Modify this instance to communicate with the Cloud Firestore emulator. - -Note: This must be called before this instance has been used to do any operations. - -Signature: - -```typescript -export declare function connectFirestoreEmulator(firestore: Firestore, host: string, port: number, options?: { - mockUserToken?: EmulatorMockTokenOptions | string; -}): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The Firestore instance to configure to connect to the emulator. | -| host | string | the emulator host (ex: localhost). | -| port | number | the emulator port (ex: 9000). | -| options | { mockUserToken?: [EmulatorMockTokenOptions](./util.md#emulatormocktokenoptions) \| string; } | | - -Returns: - -void - -## disableNetwork() - -Disables network usage for this instance. It can be re-enabled via [enableNetwork()](./firestore_.md#enablenetwork). While the network is disabled, any snapshot listeners, `getDoc()` or `getDocs()` calls will return results from cache, and any write operations will be queued until the network is restored. - -Signature: - -```typescript -export declare function disableNetwork(firestore: Firestore): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | - -Returns: - -Promise<void> - -A `Promise` that is resolved once the network has been disabled. - -## doc() - -Gets a `DocumentReference` instance that refers to the document at the specified absolute path. - -Signature: - -```typescript -export declare function doc(firestore: Firestore, path: string, ...pathSegments: string[]): DocumentReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | A reference to the root Firestore instance. | -| path | string | A slash-separated path to a document. | -| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | - -Returns: - -[DocumentReference](./firestore_.documentreference.md#documentreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> - -The `DocumentReference` instance. - -## Exceptions - -If the final path has an odd number of segments and does not point to a document. - -## enableIndexedDbPersistence() - -Attempts to enable persistent storage, if possible. - -Must be called before any other functions (other than [initializeFirestore()](./firestore_.md#initializefirestore), [getFirestore()](./firestore_.md#getfirestore) or [clearIndexedDbPersistence()](./firestore_.md#clearindexeddbpersistence). - -If this fails, `enableIndexedDbPersistence()` will reject the promise it returns. Note that even after this failure, the [Firestore](./firestore_.firestore.md#firestore_class) instance will remain usable, however offline persistence will be disabled. - -There are several reasons why this can fail, which can be identified by the `code` on the error. - -\* failed-precondition: The app is already open in another browser tab. \* unimplemented: The browser is incompatible with the offline persistence implementation. - -Signature: - -```typescript -export declare function enableIndexedDbPersistence(firestore: Firestore, persistenceSettings?: PersistenceSettings): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to enable persistence for. | -| persistenceSettings | [PersistenceSettings](./firestore_.persistencesettings.md#persistencesettings_interface) | Optional settings object to configure persistence. | - -Returns: - -Promise<void> - -A `Promise` that represents successfully enabling persistent storage. - -## enableMultiTabIndexedDbPersistence() - -Attempts to enable multi-tab persistent storage, if possible. If enabled across all tabs, all operations share access to local persistence, including shared execution of queries and latency-compensated local document updates across all connected instances. - -If this fails, `enableMultiTabIndexedDbPersistence()` will reject the promise it returns. Note that even after this failure, the [Firestore](./firestore_.firestore.md#firestore_class) instance will remain usable, however offline persistence will be disabled. - -There are several reasons why this can fail, which can be identified by the `code` on the error. - -\* failed-precondition: The app is already open in another browser tab and multi-tab is not enabled. \* unimplemented: The browser is incompatible with the offline persistence implementation. - -Signature: - -```typescript -export declare function enableMultiTabIndexedDbPersistence(firestore: Firestore): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to enable persistence for. | - -Returns: - -Promise<void> - -A `Promise` that represents successfully enabling persistent storage. - -## enableNetwork() - -Re-enables use of the network for this [Firestore](./firestore_.firestore.md#firestore_class) instance after a prior call to [disableNetwork()](./firestore_.md#disablenetwork). - -Signature: - -```typescript -export declare function enableNetwork(firestore: Firestore): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | - -Returns: - -Promise<void> - -A `Promise` that is resolved once the network has been enabled. - -## loadBundle() - -Loads a Firestore bundle into the local cache. - -Signature: - -```typescript -export declare function loadBundle(firestore: Firestore, bundleData: ReadableStream | ArrayBuffer | string): LoadBundleTask; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to load bundles for. | -| bundleData | ReadableStream<Uint8Array> \| ArrayBuffer \| string | An object representing the bundle to be loaded. Valid objects are ArrayBuffer, ReadableStream<Uint8Array> or string. | - -Returns: - -[LoadBundleTask](./firestore_.loadbundletask.md#loadbundletask_class) - -A `LoadBundleTask` object, which notifies callers with progress updates, and completion or error events. It can be used as a `Promise`. - -## namedQuery() - -Reads a Firestore [Query](./firestore_.query.md#query_class) 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](./firestore_.query.md#query_class) by name. - -Signature: - -```typescript -export declare function namedQuery(firestore: Firestore, name: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to read the query from. | -| name | string | The name of the query. | - -Returns: - -Promise<[Query](./firestore_.query.md#query_class) \| null> - -A `Promise` that is resolved with the Query or `null`. - -## onSnapshotsInSync() - -Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners. - -NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use SnapshotMetadata in the individual listeners to determine if a snapshot is from the cache or the server. - -Signature: - -```typescript -export declare function onSnapshotsInSync(firestore: Firestore, observer: { - next?: (value: void) => void; - error?: (error: FirestoreError) => void; - complete?: () => void; -}): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The instance of Firestore for synchronizing snapshots. | -| observer | { next?: (value: void) => void; error?: (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void; complete?: () => void; } | A single object containing next and error callbacks. | - -Returns: - -[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) - -An unsubscribe function that can be called to cancel the snapshot listener. - -## onSnapshotsInSync() - -Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners. - -NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use `SnapshotMetadata` in the individual listeners to determine if a snapshot is from the cache or the server. - -Signature: - -```typescript -export declare function onSnapshotsInSync(firestore: Firestore, onSync: () => void): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The Firestore instance for synchronizing snapshots. | -| onSync | () => void | A callback to be called every time all snapshot listeners are in sync with each other. | - -Returns: - -[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) - -An unsubscribe function that can be called to cancel the snapshot listener. - -## runTransaction() - -Executes the given `updateFunction` and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, Cloud Firestore retries the `updateFunction`. If it fails to commit after 5 attempts, the transaction fails. - -The maximum number of writes allowed in a single transaction is 500. - -Signature: - -```typescript -export declare function runTransaction(firestore: Firestore, updateFunction: (transaction: Transaction) => Promise, options?: TransactionOptions): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | A reference to the Firestore database to run this transaction against. | -| updateFunction | (transaction: [Transaction](./firestore_.transaction.md#transaction_class)) => Promise<T> | The function to execute within the transaction context. | -| options | [TransactionOptions](./firestore_.transactionoptions.md#transactionoptions_interface) | An options object to configure maximum number of attempts to commit. | - -Returns: - -Promise<T> - -If the transaction completed successfully or was explicitly aborted (the `updateFunction` returned a failed promise), the promise returned by the `updateFunction `is returned here. Otherwise, if the transaction failed, a rejected promise with the corresponding failure error is returned. - -## setIndexConfiguration() - -> 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. -> - -Configures indexing for local query execution. Any previous index configuration is overridden. The `Promise` resolves once the index configuration has been persisted. - -The index entries themselves are created asynchronously. You can continue to use queries that require indexing even if the indices are not yet available. Query execution will automatically start using the index once the index entries have been written. - -Indexes are only supported with IndexedDb persistence. Invoke either `enableIndexedDbPersistence()` or `enableMultiTabIndexedDbPersistence()` before setting an index configuration. If IndexedDb is not enabled, any index configuration is ignored. - -Signature: - -```typescript -export declare function setIndexConfiguration(firestore: Firestore, configuration: IndexConfiguration): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to configure indexes for. | -| configuration | [IndexConfiguration](./firestore_.indexconfiguration.md#indexconfiguration_interface) | The index definition. | - -Returns: - -Promise<void> - -A `Promise` that resolves once all indices are successfully configured. - -## Exceptions - -FirestoreError if the JSON format is invalid. - -## setIndexConfiguration() - -> 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. -> - -Configures indexing for local query execution. Any previous index configuration is overridden. The `Promise` resolves once the index configuration has been persisted. - -The index entries themselves are created asynchronously. You can continue to use queries that require indexing even if the indices are not yet available. Query execution will automatically start using the index once the index entries have been written. - -Indexes are only supported with IndexedDb persistence. Invoke either `enableIndexedDbPersistence()` or `enableMultiTabIndexedDbPersistence()` before setting an index configuration. If IndexedDb is not enabled, any index configuration is ignored. - -The method accepts the JSON format exported by the Firebase CLI (`firebase firestore:indexes`). If the JSON format is invalid, this method throws an error. - -Signature: - -```typescript -export declare function setIndexConfiguration(firestore: Firestore, json: string): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to configure indexes for. | -| json | string | The JSON format exported by the Firebase CLI. | - -Returns: - -Promise<void> - -A `Promise` that resolves once all indices are successfully configured. - -## Exceptions - -FirestoreError if the JSON format is invalid. - -## terminate() - -Terminates the provided [Firestore](./firestore_.firestore.md#firestore_class) instance. - -After calling `terminate()` only the `clearIndexedDbPersistence()` function may be used. Any other function will throw a `FirestoreError`. - -To restart after termination, create a new instance of FirebaseFirestore with [getFirestore()](./firestore_.md#getfirestore). - -Termination does not cancel any pending writes, and any promises that are awaiting a response from the server will not be resolved. If you have persistence enabled, the next time you start this instance, it will resume sending these writes to the server. - -Note: Under normal circumstances, calling `terminate()` is not required. This function is useful only when you want to force this instance to release all of its resources or in combination with `clearIndexedDbPersistence()` to ensure that all local state is destroyed between test runs. - -Signature: - -```typescript -export declare function terminate(firestore: Firestore): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | - -Returns: - -Promise<void> - -A `Promise` that is resolved when the instance has been successfully terminated. - -## waitForPendingWrites() - -Waits until all currently pending writes for the active user have been acknowledged by the backend. - -The returned promise resolves immediately if there are no outstanding writes. Otherwise, the promise waits for all previously issued writes (including those written in a previous app session), but it does not wait for writes that were added after the function is called. If you want to wait for additional writes, call `waitForPendingWrites()` again. - -Any outstanding `waitForPendingWrites()` promises are rejected during user changes. - -Signature: - -```typescript -export declare function waitForPendingWrites(firestore: Firestore): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | - -Returns: - -Promise<void> - -A `Promise` which resolves when all currently pending writes have been acknowledged by the backend. - -## writeBatch() - -Creates a write batch, used for performing multiple writes as a single atomic operation. The maximum number of writes allowed in a single [WriteBatch](./firestore_.writebatch.md#writebatch_class) is 500. - -Unlike transactions, write batches are persisted offline and therefore are preferable when you don't need to condition your writes on read data. - -Signature: - -```typescript -export declare function writeBatch(firestore: Firestore): WriteBatch; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | - -Returns: - -[WriteBatch](./firestore_.writebatch.md#writebatch_class) - -A [WriteBatch](./firestore_.writebatch.md#writebatch_class) that can be used to atomically execute multiple writes. - -## deleteField() - -Returns a sentinel for use with [updateDoc()](./firestore_lite.md#updatedoc) or [setDoc()](./firestore_lite.md#setdoc) with `{merge: true}` to mark a field for deletion. - -Signature: - -```typescript -export declare function deleteField(): FieldValue; -``` -Returns: - -[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) - -## documentId() - -Returns a special sentinel `FieldPath` to refer to the ID of a document. It can be used in queries to sort or filter by the document ID. - -Signature: - -```typescript -export declare function documentId(): FieldPath; -``` -Returns: - -[FieldPath](./firestore_.fieldpath.md#fieldpath_class) - -## getFirestore() - -Returns the existing default [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: - -```typescript -export declare function getFirestore(): Firestore; -``` -Returns: - -[Firestore](./firestore_.firestore.md#firestore_class) - -The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. - -## 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. - -Signature: - -```typescript -export declare function serverTimestamp(): FieldValue; -``` -Returns: - -[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) - -## 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. - -Signature: - -```typescript -export declare function arrayRemove(...elements: unknown[]): FieldValue; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| elements | unknown\[\] | The elements to remove from the array. | - -Returns: - -[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) - -The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()` - -## 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. - -Signature: - -```typescript -export declare function arrayUnion(...elements: unknown[]): FieldValue; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| elements | unknown\[\] | The elements to union into the array. | - -Returns: - -[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) - -The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()`. - -## orderBy() - -Creates a [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class) that sorts the query result by the specified field, optionally in descending order instead of ascending. - -Note: Documents that do not contain the specified field will not be present in the query result. - -Signature: - -```typescript -export declare function orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDirection): QueryOrderByConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldPath | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The field to sort by. | -| directionStr | [OrderByDirection](./firestore_.md#orderbydirection) | Optional direction to sort by ('asc' or 'desc'). If not specified, order will be ascending. | - -Returns: - -[QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class) - -The created [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class). - -## where() - -Creates a [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) that enforces that documents must contain the specified field and that the value should satisfy the relation constraint provided. - -Signature: - -```typescript -export declare function where(fieldPath: string | FieldPath, opStr: WhereFilterOp, value: unknown): QueryFieldFilterConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldPath | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The path to compare | -| opStr | [WhereFilterOp](./firestore_.md#wherefilterop) | The operation string (e.g "&lt;", "&lt;=", "==", "&lt;", "&lt;=", "!="). | -| value | unknown | The value for comparison | - -Returns: - -[QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) - -The created [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class). - -## endAt() - -Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. - -Signature: - -```typescript -export declare function endAt(...fieldValues: unknown[]): QueryEndAtConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldValues | unknown\[\] | The field values to end this query at, in order of the query's order by. | - -Returns: - -[QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) - -A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` - -## endBefore() - -Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. - -Signature: - -```typescript -export declare function endBefore(...fieldValues: unknown[]): QueryEndAtConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldValues | unknown\[\] | The field values to end this query before, in order of the query's order by. | - -Returns: - -[QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) - -A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` - -## startAfter() - -Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. - -Signature: - -```typescript -export declare function startAfter(...fieldValues: unknown[]): QueryStartAtConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldValues | unknown\[\] | The field values to start this query after, in order of the query's order by. | - -Returns: - -[QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) - -A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()` - -## startAt() - -Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. - -Signature: - -```typescript -export declare function startAt(...fieldValues: unknown[]): QueryStartAtConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldValues | unknown\[\] | The field values to start this query at, in order of the query's order by. | - -Returns: - -[QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) - -A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()`. - -## aggregateQuerySnapshotEqual() - -Compares two `AggregateQuerySnapshot` instances for equality. - -Two `AggregateQuerySnapshot` instances are considered "equal" if they have underlying queries that compare equal, and the same data. - -Signature: - -```typescript -export declare function aggregateQuerySnapshotEqual(left: AggregateQuerySnapshot, right: AggregateQuerySnapshot): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| left | [AggregateQuerySnapshot](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<T> | The first AggregateQuerySnapshot to compare. | -| right | [AggregateQuerySnapshot](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<T> | The second AggregateQuerySnapshot to compare. | - -Returns: - -boolean - -`true` if the objects are "equal", as defined above, or `false` otherwise. - -## queryEqual() - -Returns true if the provided queries point to the same collection and apply the same constraints. - -Signature: - -```typescript -export declare function queryEqual(left: Query, right: Query): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| left | [Query](./firestore_.query.md#query_class)<T> | A Query to compare. | -| right | [Query](./firestore_.query.md#query_class)<T> | A Query to compare. | - -Returns: - -boolean - -true if the references point to the same location in the same Firestore database. - -## refEqual() - -Returns true if the provided references are equal. - -Signature: - -```typescript -export declare function refEqual(left: DocumentReference | CollectionReference, right: DocumentReference | CollectionReference): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| left | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> \| [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | A reference to compare. | -| right | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> \| [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | A reference to compare. | - -Returns: - -boolean - -true if the references point to the same location in the same Firestore database. - -## snapshotEqual() - -Returns true if the provided snapshots are equal. - -Signature: - -```typescript -export declare function snapshotEqual(left: DocumentSnapshot | QuerySnapshot, right: DocumentSnapshot | QuerySnapshot): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| left | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T> \| [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T> | A snapshot to compare. | -| right | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T> \| [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T> | A snapshot to compare. | - -Returns: - -boolean - -true if the snapshots are equal. - -## limit() - -Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the first matching documents. - -Signature: - -```typescript -export declare function limit(limit: number): QueryLimitConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| limit | number | The maximum number of items to return. | - -Returns: - -[QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) - -The created [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class). - -## limitToLast() - -Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the last matching documents. - -You must specify at least one `orderBy` clause for `limitToLast` queries, otherwise an exception will be thrown during execution. - -Signature: - -```typescript -export declare function limitToLast(limit: number): QueryLimitConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| limit | number | The maximum number of items to return. | - -Returns: - -[QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) - -The created [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class). - -## setLogLevel() - -Sets the verbosity of Cloud Firestore logs (debug, error, or silent). - -Signature: - -```typescript -export declare function setLogLevel(logLevel: LogLevel): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| logLevel | LogLevel | The verbosity you set for activity and error logging. Can be any of the following values:

  • debug for the most verbose logging level, primarily for debugging.
  • error to log errors only.
  • silent to turn off logging.
| - -Returns: - -void - -## increment() - -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 increment the field's current value by the given value. - -If either the operand or the current field value uses floating point precision, all arithmetic follows IEEE 754 semantics. If both values are integers, values outside of JavaScript's safe number range (`Number.MIN_SAFE_INTEGER` to `Number.MAX_SAFE_INTEGER`) are also subject to precision loss. Furthermore, once processed by the Firestore backend, all integer operations are capped between -2^63 and 2^63-1. - -If the current field value is not of type `number`, or if the field does not yet exist, the transformation sets the field to the given value. - -Signature: - -```typescript -export declare function increment(n: number): FieldValue; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| n | number | The value to increment by. | - -Returns: - -[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) - -The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()` - -## getCountFromServer() - -Calculates the number of documents in the result set of the given query, without actually downloading the documents. - -Using this function to count the documents is efficient because only the final count, not the documents' data, is downloaded. This function can even count the documents if the result set would be prohibitively large to download entirely (e.g. thousands of documents). - -The result received from the server is presented, unaltered, without considering any local state. That is, documents in the local cache are not taken into consideration, neither are local modifications not yet synchronized with the server. Previously-downloaded results, if any, are not used: every request using this source necessarily involves a round trip to the server. - -Signature: - -```typescript -export declare function getCountFromServer(query: Query): Promise; -}>>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./firestore_.query.md#query_class)<unknown> | The query whose result set size to calculate. | - -Returns: - -Promise<[AggregateQuerySnapshot](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<{ count: [AggregateField](./firestore_.aggregatefield.md#aggregatefield_class)<number>; }>> - -A Promise that will be resolved with the count; the count can be retrieved from `snapshot.data().count`, where `snapshot` is the `AggregateQuerySnapshot` to which the returned Promise resolves. - -## getDocs() - -Executes the query and returns the results as a `QuerySnapshot`. - -Note: `getDocs()` attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. To specify this behavior, invoke [getDocsFromCache()](./firestore_.md#getdocsfromcache) or [getDocsFromServer()](./firestore_.md#getdocsfromserver). - -Signature: - -```typescript -export declare function getDocs(query: Query): Promise>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./firestore_.query.md#query_class)<T> | | - -Returns: - -Promise<[QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>> - -A `Promise` that will be resolved with the results of the query. - -## getDocsFromCache() - -Executes the query and returns the results as a `QuerySnapshot` from cache. Returns an empty result set if no documents matching the query are currently cached. - -Signature: - -```typescript -export declare function getDocsFromCache(query: Query): Promise>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./firestore_.query.md#query_class)<T> | | - -Returns: - -Promise<[QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>> - -A `Promise` that will be resolved with the results of the query. - -## getDocsFromServer() - -Executes the query and returns the results as a `QuerySnapshot` from the server. Returns an error if the network is not available. - -Signature: - -```typescript -export declare function getDocsFromServer(query: Query): Promise>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./firestore_.query.md#query_class)<T> | | - -Returns: - -Promise<[QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>> - -A `Promise` that will be resolved with the results of the query. - -## onSnapshot() - -Attaches a listener for `QuerySnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. The listener can be cancelled by calling the function that is returned when `onSnapshot` is called. - -NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. - -Signature: - -```typescript -export declare function onSnapshot(query: Query, observer: { - next?: (snapshot: QuerySnapshot) => void; - error?: (error: FirestoreError) => void; - complete?: () => void; -}): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./firestore_.query.md#query_class)<T> | The query to listen to. | -| observer | { next?: (snapshot: [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>) => void; error?: (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void; complete?: () => void; } | A single object containing next and error callbacks. | - -Returns: - -[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) - -An unsubscribe function that can be called to cancel the snapshot listener. - -## onSnapshot() - -Attaches a listener for `QuerySnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. The listener can be cancelled by calling the function that is returned when `onSnapshot` is called. - -NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. - -Signature: - -```typescript -export declare function onSnapshot(query: Query, options: SnapshotListenOptions, observer: { - next?: (snapshot: QuerySnapshot) => void; - error?: (error: FirestoreError) => void; - complete?: () => void; -}): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./firestore_.query.md#query_class)<T> | The query to listen to. | -| options | [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | Options controlling the listen behavior. | -| observer | { next?: (snapshot: [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>) => void; error?: (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void; complete?: () => void; } | A single object containing next and error callbacks. | - -Returns: - -[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) - -An unsubscribe function that can be called to cancel the snapshot listener. - -## onSnapshot() - -Attaches a listener for `QuerySnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. The listener can be cancelled by calling the function that is returned when `onSnapshot` is called. - -NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. - -Signature: - -```typescript -export declare function onSnapshot(query: Query, onNext: (snapshot: QuerySnapshot) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./firestore_.query.md#query_class)<T> | The query to listen to. | -| onNext | (snapshot: [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>) => void | A callback to be called every time a new QuerySnapshot is available. | -| onError | (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void | A callback to be called if the listen fails or is cancelled. No further callbacks will occur. | -| onCompletion | () => void | Can be provided, but will not be called since streams are never ending. | - -Returns: - -[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) - -An unsubscribe function that can be called to cancel the snapshot listener. - -## onSnapshot() - -Attaches a listener for `QuerySnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. The listener can be cancelled by calling the function that is returned when `onSnapshot` is called. - -NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. - -Signature: - -```typescript -export declare function onSnapshot(query: Query, options: SnapshotListenOptions, onNext: (snapshot: QuerySnapshot) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./firestore_.query.md#query_class)<T> | The query to listen to. | -| options | [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | Options controlling the listen behavior. | -| onNext | (snapshot: [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>) => void | A callback to be called every time a new QuerySnapshot is available. | -| onError | (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void | A callback to be called if the listen fails or is cancelled. No further callbacks will occur. | -| onCompletion | () => void | Can be provided, but will not be called since streams are never ending. | - -Returns: - -[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) - -An unsubscribe function that can be called to cancel the snapshot listener. - -## query() - -Creates a new immutable instance of [Query](./firestore_.query.md#query_class) that is extended to also include additional query constraints. - -Signature: - -```typescript -export declare function query(query: Query, ...queryConstraints: QueryConstraint[]): Query; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./firestore_.query.md#query_class)<T> | The [Query](./firestore_.query.md#query_class) instance to use as a base for the new constraints. | -| queryConstraints | [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class)\[\] | The list of [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class)s to apply. | - -Returns: - -[Query](./firestore_.query.md#query_class)<T> - -## Exceptions - -if any of the provided query constraints cannot be combined with the existing or new constraints. - -## addDoc() - -Add a new document to specified `CollectionReference` with the given data, assigning it a document ID automatically. - -Signature: - -```typescript -export declare function addDoc(reference: CollectionReference, data: WithFieldValue): Promise>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | A reference to the collection to add this document to. | -| data | [WithFieldValue](./firestore_.md#withfieldvalue)<T> | An Object containing the data for the new document. | - -Returns: - -Promise<[DocumentReference](./firestore_.documentreference.md#documentreference_class)<T>> - -A `Promise` resolved with a `DocumentReference` pointing to the newly created document after it has been written to the backend (Note that it won't resolve while you're offline). - -## collection() - -Gets a `CollectionReference` instance that refers to a subcollection of `reference` at the the specified relative path. - -Signature: - -```typescript -export declare function collection(reference: CollectionReference, path: string, ...pathSegments: string[]): CollectionReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<unknown> | A reference to a collection. | -| path | string | A slash-separated path to a collection. | -| pathSegments | string\[\] | Additional path segments to apply relative to the first argument. | - -Returns: - -[CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> - -The `CollectionReference` instance. - -## Exceptions - -If the final path has an even number of segments and does not point to a collection. - -## collection() - -Gets a `CollectionReference` instance that refers to a subcollection of `reference` at the the specified relative path. - -Signature: - -```typescript -export declare function collection(reference: DocumentReference, path: string, ...pathSegments: string[]): CollectionReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class) | A reference to a Firestore document. | -| path | string | A slash-separated path to a collection. | -| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | - -Returns: - -[CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> - -The `CollectionReference` instance. - -## Exceptions - -If the final path has an even number of segments and does not point to a collection. - -## deleteDoc() - -Deletes the document referred to by the specified `DocumentReference`. - -Signature: - -```typescript -export declare function deleteDoc(reference: DocumentReference): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to the document to delete. | - -Returns: - -Promise<void> - -A Promise resolved once the document has been successfully deleted from the backend (note that it won't resolve while you're offline). - -## doc() - -Gets a `DocumentReference` instance that refers to a document within `reference` at the specified relative path. If no path is specified, an automatically-generated unique ID will be used for the returned `DocumentReference`. - -Signature: - -```typescript -export declare function doc(reference: CollectionReference, path?: string, ...pathSegments: string[]): DocumentReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | A reference to a collection. | -| path | string | A slash-separated path to a document. Has to be omitted to use auto-genrated IDs. | -| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | - -Returns: - -[DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> - -The `DocumentReference` instance. - -## Exceptions - -If the final path has an odd number of segments and does not point to a document. - -## doc() - -Gets a `DocumentReference` instance that refers to a document within `reference` at the specified relative path. - -Signature: - -```typescript -export declare function doc(reference: DocumentReference, path: string, ...pathSegments: string[]): DocumentReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to a Firestore document. | -| path | string | A slash-separated path to a document. | -| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | - -Returns: - -[DocumentReference](./firestore_.documentreference.md#documentreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> - -The `DocumentReference` instance. - -## Exceptions - -If the final path has an odd number of segments and does not point to a document. - -## getDoc() - -Reads the document referred to by this `DocumentReference`. - -Note: `getDoc()` attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. To specify this behavior, invoke [getDocFromCache()](./firestore_.md#getdocfromcache) or [getDocFromServer()](./firestore_.md#getdocfromserver). - -Signature: - -```typescript -export declare function getDoc(reference: DocumentReference): Promise>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | The reference of the document to fetch. | - -Returns: - -Promise<[DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>> - -A Promise resolved with a `DocumentSnapshot` containing the current document contents. - -## getDocFromCache() - -Reads the document referred to by this `DocumentReference` from cache. Returns an error if the document is not currently cached. - -Signature: - -```typescript -export declare function getDocFromCache(reference: DocumentReference): Promise>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | | - -Returns: - -Promise<[DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>> - -A `Promise` resolved with a `DocumentSnapshot` containing the current document contents. - -## getDocFromServer() - -Reads the document referred to by this `DocumentReference` from the server. Returns an error if the network is not available. - -Signature: - -```typescript -export declare function getDocFromServer(reference: DocumentReference): Promise>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | | - -Returns: - -Promise<[DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>> - -A `Promise` resolved with a `DocumentSnapshot` containing the current document contents. - -## onSnapshot() - -Attaches a listener for `DocumentSnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. - -NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. - -Signature: - -```typescript -export declare function onSnapshot(reference: DocumentReference, observer: { - next?: (snapshot: DocumentSnapshot) => void; - error?: (error: FirestoreError) => void; - complete?: () => void; -}): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to listen to. | -| observer | { next?: (snapshot: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>) => void; error?: (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void; complete?: () => void; } | A single object containing next and error callbacks. | - -Returns: - -[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) - -An unsubscribe function that can be called to cancel the snapshot listener. - -## onSnapshot() - -Attaches a listener for `DocumentSnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. - -NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. - -Signature: - -```typescript -export declare function onSnapshot(reference: DocumentReference, options: SnapshotListenOptions, observer: { - next?: (snapshot: DocumentSnapshot) => void; - error?: (error: FirestoreError) => void; - complete?: () => void; -}): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to listen to. | -| options | [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | Options controlling the listen behavior. | -| observer | { next?: (snapshot: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>) => void; error?: (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void; complete?: () => void; } | A single object containing next and error callbacks. | - -Returns: - -[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) - -An unsubscribe function that can be called to cancel the snapshot listener. - -## onSnapshot() - -Attaches a listener for `DocumentSnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. - -NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. - -Signature: - -```typescript -export declare function onSnapshot(reference: DocumentReference, onNext: (snapshot: DocumentSnapshot) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to listen to. | -| onNext | (snapshot: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>) => void | A callback to be called every time a new DocumentSnapshot is available. | -| onError | (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void | A callback to be called if the listen fails or is cancelled. No further callbacks will occur. | -| onCompletion | () => void | Can be provided, but will not be called since streams are never ending. | - -Returns: - -[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) - -An unsubscribe function that can be called to cancel the snapshot listener. - -## onSnapshot() - -Attaches a listener for `DocumentSnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. - -NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. - -Signature: - -```typescript -export declare function onSnapshot(reference: DocumentReference, options: SnapshotListenOptions, onNext: (snapshot: DocumentSnapshot) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to listen to. | -| options | [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | Options controlling the listen behavior. | -| onNext | (snapshot: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>) => void | A callback to be called every time a new DocumentSnapshot is available. | -| onError | (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void | A callback to be called if the listen fails or is cancelled. No further callbacks will occur. | -| onCompletion | () => void | Can be provided, but will not be called since streams are never ending. | - -Returns: - -[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) - -An unsubscribe function that can be called to cancel the snapshot listener. - -## setDoc() - -Writes to the document referred to by this `DocumentReference`. If the document does not yet exist, it will be created. - -Signature: - -```typescript -export declare function setDoc(reference: DocumentReference, data: WithFieldValue): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to write. | -| data | [WithFieldValue](./firestore_.md#withfieldvalue)<T> | A map of the fields and values for the document. | - -Returns: - -Promise<void> - -A `Promise` resolved once the data has been successfully written to the backend (note that it won't resolve while you're offline). - -## setDoc() - -Writes to the document referred to by the specified `DocumentReference`. If the document does not yet exist, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. - -Signature: - -```typescript -export declare function setDoc(reference: DocumentReference, data: PartialWithFieldValue, options: SetOptions): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to write. | -| data | [PartialWithFieldValue](./firestore_.md#partialwithfieldvalue)<T> | A map of the fields and values for the document. | -| options | [SetOptions](./firestore_.md#setoptions) | An object to configure the set behavior. | - -Returns: - -Promise<void> - -A Promise resolved once the data has been successfully written to the backend (note that it won't resolve while you're offline). - -## updateDoc() - -Updates fields in the document referred to by the specified `DocumentReference`. The update will fail if applied to a document that does not exist. - -Signature: - -```typescript -export declare function updateDoc(reference: DocumentReference, data: UpdateData): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to update. | -| data | [UpdateData](./firestore_.md#updatedata)<T> | An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document. | - -Returns: - -Promise<void> - -A `Promise` resolved once the data has been successfully written to the backend (note that it won't resolve while you're offline). - -## updateDoc() - -Updates fields in the document referred to by the specified `DocumentReference` The update will fail if applied to a document that does not exist. - -Nested fields can be updated by providing dot-separated field path strings or by providing `FieldPath` objects. - -Signature: - -```typescript -export declare function updateDoc(reference: DocumentReference, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to the document to update. | -| field | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The first field to update. | -| value | unknown | The first value. | -| moreFieldsAndValues | unknown\[\] | Additional key value pairs. | - -Returns: - -Promise<void> - -A `Promise` resolved once the data has been successfully written to the backend (note that it won't resolve while you're offline). - -## endAt() - -Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided document (inclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. - -Signature: - -```typescript -export declare function endAt(snapshot: DocumentSnapshot): QueryEndAtConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| snapshot | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to end at. | - -Returns: - -[QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) - -A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` - -## endBefore() - -Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. - -Signature: - -```typescript -export declare function endBefore(snapshot: DocumentSnapshot): QueryEndAtConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| snapshot | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to end before. | - -Returns: - -[QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) - -A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` - -## startAfter() - -Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. - -Signature: - -```typescript -export declare function startAfter(snapshot: DocumentSnapshot): QueryStartAtConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| snapshot | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to start after. | - -Returns: - -[QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) - -A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()` - -## startAt() - -Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the `orderBy` of this query. - -Signature: - -```typescript -export declare function startAt(snapshot: DocumentSnapshot): QueryStartAtConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| snapshot | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to start at. | - -Returns: - -[QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) - -A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()`. - -## CACHE\_SIZE\_UNLIMITED - -Constant used to indicate the LRU garbage collection should be disabled. Set this value as the `cacheSizeBytes` on the settings passed to the [Firestore](./firestore_.firestore.md#firestore_class) instance. - -Signature: - -```typescript -CACHE_SIZE_UNLIMITED = -1 -``` - -## AddPrefixToKeys - -Returns a new map where every key is prefixed with the outer key appended to a dot. - -Signature: - -```typescript -export declare type AddPrefixToKeys> = { - [K in keyof T & string as `${Prefix}.${K}`]+?: T[K]; -}; -``` - -## AggregateFieldType - -The union of all `AggregateField` types that are supported by Firestore. - -Signature: - -```typescript -export declare type AggregateFieldType = AggregateField; -``` - -## AggregateSpecData - -A type whose keys are taken from an `AggregateSpec`, and whose values are the result of the aggregation performed by the corresponding `AggregateField` from the input `AggregateSpec`. - -Signature: - -```typescript -export declare type AggregateSpecData = { - [P in keyof T]: T[P] extends AggregateField ? U : never; -}; -``` - -## ChildUpdateFields - -Helper for calculating the nested fields for a given type T1. This is needed to distribute union types such as `undefined | {...}` (happens for optional props) or `{a: A} | {b: B}`. - -In this use case, `V` is used to distribute the union types of `T[K]` on `Record`, since `T[K]` is evaluated as an expression and not distributed. - -See https://www.typescriptlang.org/docs/handbook/advanced-types.html\#distributive-conditional-types - -Signature: - -```typescript -export declare type ChildUpdateFields = V extends Record ? AddPrefixToKeys> : never; -``` - -## DocumentChangeType - -The type of a `DocumentChange` may be 'added', 'removed', or 'modified'. - -Signature: - -```typescript -export declare type DocumentChangeType = 'added' | 'removed' | 'modified'; -``` - -## FirestoreErrorCode - -The set of Firestore status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.md - -Possible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (e.g. an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation. - -Signature: - -```typescript -export declare type FirestoreErrorCode = 'cancelled' | 'unknown' | 'invalid-argument' | 'deadline-exceeded' | 'not-found' | 'already-exists' | 'permission-denied' | 'resource-exhausted' | 'failed-precondition' | 'aborted' | 'out-of-range' | 'unimplemented' | 'internal' | 'unavailable' | 'data-loss' | 'unauthenticated'; -``` - -## NestedUpdateFields - -For each field (e.g. 'bar'), find all nested keys (e.g. {'bar.baz': T1, 'bar.qux': T2}). Intersect them together to make a single map containing all possible keys that are all marked as optional - -Signature: - -```typescript -export declare type NestedUpdateFields> = UnionToIntersection<{ - [K in keyof T & string]: ChildUpdateFields; -}[keyof T & string]>; -``` - -## OrderByDirection - -The direction of a [orderBy()](./firestore_.md#orderby) clause is specified as 'desc' or 'asc' (descending or ascending). - -Signature: - -```typescript -export declare type OrderByDirection = 'desc' | 'asc'; -``` - -## PartialWithFieldValue - -Similar to Typescript's `Partial`, but allows nested fields to be omitted and FieldValues to be passed in as property values. - -Signature: - -```typescript -export declare type PartialWithFieldValue = Partial | (T extends Primitive ? T : T extends {} ? { - [K in keyof T]?: PartialWithFieldValue | FieldValue; -} : never); -``` - -## Primitive - -Primitive types. - -Signature: - -```typescript -export declare type Primitive = string | number | boolean | undefined | null; -``` - -## QueryConstraintType - -Describes the different query constraints available in this SDK. - -Signature: - -```typescript -export declare type QueryConstraintType = 'where' | 'orderBy' | 'limit' | 'limitToLast' | 'startAt' | 'startAfter' | 'endAt' | 'endBefore'; -``` - -## QueryNonFilterConstraint - -`QueryNonFilterConstraint` is a helper union type that represents QueryConstraints which are used to narrow or order the set of documents, but that do not explicitly filter on a document field. `QueryNonFilterConstraint`s are created by invoking [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains the `QueryConstraint`. - -Signature: - -```typescript -export declare type QueryNonFilterConstraint = QueryOrderByConstraint | QueryLimitConstraint | QueryStartAtConstraint | QueryEndAtConstraint; -``` - -## SetOptions - -An options object that configures the behavior of [setDoc()](./firestore_lite.md#setdoc), and calls. These calls can be configured to perform granular merges instead of overwriting the target documents in their entirety by providing a `SetOptions` with `merge: true`. - -Signature: - -```typescript -export declare type SetOptions = { - readonly merge?: boolean; -} | { - readonly mergeFields?: Array; -}; -``` - -## 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. - -Signature: - -```typescript -export declare type TaskState = 'Error' | 'Running' | 'Success'; -``` - -## UnionToIntersection - -Given a union type `U = T1 | T2 | ...`, returns an intersected type `(T1 & T2 & ...)`. - -Uses distributive conditional types and inference from conditional types. This works because multiple candidates for the same type variable in contra-variant positions causes an intersection type to be inferred. https://www.typescriptlang.org/docs/handbook/advanced-types.html\#type-inference-in-conditional-types https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection-type - -Signature: - -```typescript -export declare type UnionToIntersection = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never; -``` - -## UpdateData - -Update data (for use with [updateDoc()](./firestore_.md#updatedoc)) that consists of field paths (e.g. 'foo' or 'foo.baz') mapped to values. Fields that contain dots reference nested fields within the document. FieldValues can be passed in as property values. - -Signature: - -```typescript -export declare type UpdateData = T extends Primitive ? T : T extends {} ? { - [K in keyof T]?: UpdateData | FieldValue; -} & NestedUpdateFields : Partial; -``` - -## WhereFilterOp - -Filter conditions in a [where()](./firestore_.md#where) clause are specified using the strings '&lt;', '&lt;=', '==', '!=', '&gt;=', '&gt;', 'array-contains', 'in', 'array-contains-any', and 'not-in'. - -Signature: - -```typescript -export declare type WhereFilterOp = '<' | '<=' | '==' | '!=' | '>=' | '>' | 'array-contains' | 'in' | 'array-contains-any' | 'not-in'; -``` - -## WithFieldValue - -Allows FieldValues to be passed in as a property value while maintaining type safety. - -Signature: - -```typescript -export declare type WithFieldValue = T | (T extends Primitive ? T : T extends {} ? { - [K in keyof T]: WithFieldValue | FieldValue; -} : never); -``` diff --git a/docs-devsite/firestore_.persistencesettings.md b/docs-devsite/firestore_.persistencesettings.md deleted file mode 100644 index c84cde1ed13..00000000000 --- a/docs-devsite/firestore_.persistencesettings.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# PersistenceSettings interface -Settings that can be passed to `enableIndexedDbPersistence()` to configure Firestore persistence. - -Signature: - -```typescript -export declare interface PersistenceSettings -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [forceOwnership](./firestore_.persistencesettings.md#persistencesettingsforceownership) | boolean | Whether to force enable persistence for the client. This cannot be used with multi-tab synchronization and is primarily intended for use with Web Workers. Setting this to true will enable persistence, but cause other tabs using persistence to fail. | - -## PersistenceSettings.forceOwnership - -Whether to force enable persistence for the client. This cannot be used with multi-tab synchronization and is primarily intended for use with Web Workers. Setting this to `true` will enable persistence, but cause other tabs using persistence to fail. - -Signature: - -```typescript -forceOwnership?: boolean; -``` diff --git a/docs-devsite/firestore_.query.md b/docs-devsite/firestore_.query.md deleted file mode 100644 index 1961c2cc5f3..00000000000 --- a/docs-devsite/firestore_.query.md +++ /dev/null @@ -1,125 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Query class -A `Query` refers to a query which you can read or listen to. You can also construct refined `Query` objects by adding filters and ordering. - -Signature: - -```typescript -export declare class Query -``` - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)()](./firestore_.query.md#queryconstructor) | | Constructs a new instance of the Query class | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [converter](./firestore_.query.md#queryconverter) | | [FirestoreDataConverter](./firestore_.firestoredataconverter.md#firestoredataconverter_interface)<T> \| null | If provided, the FirestoreDataConverter associated with this instance. | -| [firestore](./firestore_.query.md#queryfirestore) | | [Firestore](./firestore_.firestore.md#firestore_class) | The Firestore instance for the Firestore database (useful for performing transactions, etc.). | -| [type](./firestore_.query.md#querytype) | | 'query' \| 'collection' | The type of this Firestore reference. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [withConverter(converter)](./firestore_.query.md#querywithconverter) | | Removes the current converter. | -| [withConverter(converter)](./firestore_.query.md#querywithconverter) | | Applies a custom data converter to this query, allowing you to use your own custom model objects with Firestore. When you call [getDocs()](./firestore_.md#getdocs) with the returned query, the provided converter will convert between Firestore data and your custom type U. | - -## Query.(constructor) - -Constructs a new instance of the `Query` class - -Signature: - -```typescript -protected constructor(); -``` - -## Query.converter - -If provided, the `FirestoreDataConverter` associated with this instance. - -Signature: - -```typescript -readonly converter: FirestoreDataConverter | null; -``` - -## Query.firestore - -The `Firestore` instance for the Firestore database (useful for performing transactions, etc.). - -Signature: - -```typescript -readonly firestore: Firestore; -``` - -## Query.type - -The type of this Firestore reference. - -Signature: - -```typescript -readonly type: 'query' | 'collection'; -``` - -## Query.withConverter() - -Removes the current converter. - -Signature: - -```typescript -withConverter(converter: null): Query; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| converter | null | null removes the current converter. | - -Returns: - -[Query](./firestore_.query.md#query_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> - -A `Query` that does not use a converter. - -## Query.withConverter() - -Applies a custom data converter to this query, allowing you to use your own custom model objects with Firestore. When you call [getDocs()](./firestore_.md#getdocs) with the returned query, the provided converter will convert between Firestore data and your custom type `U`. - -Signature: - -```typescript -withConverter(converter: FirestoreDataConverter): Query; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| converter | [FirestoreDataConverter](./firestore_.firestoredataconverter.md#firestoredataconverter_interface)<U> | Converts objects to and from Firestore. | - -Returns: - -[Query](./firestore_.query.md#query_class)<U> - -A `Query` that uses the provided converter. - diff --git a/docs-devsite/firestore_.queryconstraint.md b/docs-devsite/firestore_.queryconstraint.md deleted file mode 100644 index 77ebddf1c65..00000000000 --- a/docs-devsite/firestore_.queryconstraint.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryConstraint class -A `QueryConstraint` is used to narrow the set of documents returned by a Firestore query. `QueryConstraint`s are created by invoking [where()](./firestore_.md#where), [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit), [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryConstraint`. - -Signature: - -```typescript -export declare abstract class QueryConstraint -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_.queryconstraint.md#queryconstrainttype) | | [QueryConstraintType](./firestore_.md#queryconstrainttype) | The type of this query constraint | - -## QueryConstraint.type - -The type of this query constraint - -Signature: - -```typescript -abstract readonly type: QueryConstraintType; -``` diff --git a/docs-devsite/firestore_.querydocumentsnapshot.md b/docs-devsite/firestore_.querydocumentsnapshot.md deleted file mode 100644 index 0755a11915f..00000000000 --- a/docs-devsite/firestore_.querydocumentsnapshot.md +++ /dev/null @@ -1,54 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryDocumentSnapshot class -A `QueryDocumentSnapshot` contains data read from a document in your Firestore database as part of a query. The document is guaranteed to exist and its data can be extracted with `.data()` or `.get()` to get a specific field. - -A `QueryDocumentSnapshot` offers the same API surface as a `DocumentSnapshot`. Since query results contain only existing documents, the `exists` property will always be true and `data()` will never return 'undefined'. - -Signature: - -```typescript -export declare class QueryDocumentSnapshot extends DocumentSnapshot -``` -Extends: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T> - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [data(options)](./firestore_.querydocumentsnapshot.md#querydocumentsnapshotdata) | | Retrieves all fields in the document as an Object.By default, serverTimestamp() values that have not yet been set to their final value will be returned as null. You can override this by passing an options object. | - -## QueryDocumentSnapshot.data() - -Retrieves all fields in the document as an `Object`. - -By default, `serverTimestamp()` values that have not yet been set to their final value will be returned as `null`. You can override this by passing an options object. - -Signature: - -```typescript -/** @override */ -data(options?: SnapshotOptions): T; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| options | [SnapshotOptions](./firestore_.snapshotoptions.md#snapshotoptions_interface) | An options object to configure how data is retrieved from the snapshot (for example the desired behavior for server timestamps that have not yet been set to their final value). | - -Returns: - -T - -An `Object` containing all fields in the document. - diff --git a/docs-devsite/firestore_.queryendatconstraint.md b/docs-devsite/firestore_.queryendatconstraint.md deleted file mode 100644 index 44dcddab71b..00000000000 --- a/docs-devsite/firestore_.queryendatconstraint.md +++ /dev/null @@ -1,36 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryEndAtConstraint class -A `QueryEndAtConstraint` is used to exclude documents from the end of a result set returned by a Firestore query. `QueryEndAtConstraint`s are created by invoking [endAt()](./firestore_.md#endat) or [endBefore()](./firestore_.md#endbefore) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryEndAtConstraint`. - -Signature: - -```typescript -export declare class QueryEndAtConstraint extends QueryConstraint -``` -Extends: [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_.queryendatconstraint.md#queryendatconstrainttype) | | 'endBefore' \| 'endAt' | The type of this query constraint | - -## QueryEndAtConstraint.type - -The type of this query constraint - -Signature: - -```typescript -readonly type: 'endBefore' | 'endAt'; -``` diff --git a/docs-devsite/firestore_.queryfieldfilterconstraint.md b/docs-devsite/firestore_.queryfieldfilterconstraint.md deleted file mode 100644 index 18710b6aa99..00000000000 --- a/docs-devsite/firestore_.queryfieldfilterconstraint.md +++ /dev/null @@ -1,36 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryFieldFilterConstraint class -A `QueryFieldFilterConstraint` is used to narrow the set of documents returned by a Firestore query by filtering on one or more document fields. `QueryFieldFilterConstraint`s are created by invoking [where()](./firestore_.md#where) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryFieldFilterConstraint`. - -Signature: - -```typescript -export declare class QueryFieldFilterConstraint extends QueryConstraint -``` -Extends: [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstrainttype) | | (not declared) | The type of this query constraint | - -## QueryFieldFilterConstraint.type - -The type of this query constraint - -Signature: - -```typescript -readonly type = "where"; -``` diff --git a/docs-devsite/firestore_.querylimitconstraint.md b/docs-devsite/firestore_.querylimitconstraint.md deleted file mode 100644 index 72b06d61073..00000000000 --- a/docs-devsite/firestore_.querylimitconstraint.md +++ /dev/null @@ -1,36 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryLimitConstraint class -A `QueryLimitConstraint` is used to limit the number of documents returned by a Firestore query. `QueryLimitConstraint`s are created by invoking [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryLimitConstraint`. - -Signature: - -```typescript -export declare class QueryLimitConstraint extends QueryConstraint -``` -Extends: [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_.querylimitconstraint.md#querylimitconstrainttype) | | 'limit' \| 'limitToLast' | The type of this query constraint | - -## QueryLimitConstraint.type - -The type of this query constraint - -Signature: - -```typescript -readonly type: 'limit' | 'limitToLast'; -``` diff --git a/docs-devsite/firestore_.queryorderbyconstraint.md b/docs-devsite/firestore_.queryorderbyconstraint.md deleted file mode 100644 index 6f24ac985dd..00000000000 --- a/docs-devsite/firestore_.queryorderbyconstraint.md +++ /dev/null @@ -1,38 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryOrderByConstraint class -A `QueryOrderByConstraint` is used to sort the set of documents returned by a Firestore query. `QueryOrderByConstraint`s are created by invoking [orderBy()](./firestore_.md#orderby) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryOrderByConstraint`. - -Note: Documents that do not contain the orderBy field will not be present in the query result. - -Signature: - -```typescript -export declare class QueryOrderByConstraint extends QueryConstraint -``` -Extends: [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_.queryorderbyconstraint.md#queryorderbyconstrainttype) | | (not declared) | The type of this query constraint | - -## QueryOrderByConstraint.type - -The type of this query constraint - -Signature: - -```typescript -readonly type = "orderBy"; -``` diff --git a/docs-devsite/firestore_.querysnapshot.md b/docs-devsite/firestore_.querysnapshot.md deleted file mode 100644 index 0abb869c003..00000000000 --- a/docs-devsite/firestore_.querysnapshot.md +++ /dev/null @@ -1,128 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QuerySnapshot class -A `QuerySnapshot` contains zero or more `DocumentSnapshot` objects representing the results of a query. The documents can be accessed as an array via the `docs` property or enumerated using the `forEach` method. The number of documents can be determined via the `empty` and `size` properties. - -Signature: - -```typescript -export declare class QuerySnapshot -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [docs](./firestore_.querysnapshot.md#querysnapshotdocs) | | Array<[QueryDocumentSnapshot](./firestore_.querydocumentsnapshot.md#querydocumentsnapshot_class)<T>> | An array of all the documents in the QuerySnapshot. | -| [empty](./firestore_.querysnapshot.md#querysnapshotempty) | | boolean | True if there are no documents in the QuerySnapshot. | -| [metadata](./firestore_.querysnapshot.md#querysnapshotmetadata) | | [SnapshotMetadata](./firestore_.snapshotmetadata.md#snapshotmetadata_class) | Metadata about this snapshot, concerning its source and if it has local modifications. | -| [query](./firestore_.querysnapshot.md#querysnapshotquery) | | [Query](./firestore_.query.md#query_class)<T> | The query on which you called get or onSnapshot in order to get this QuerySnapshot. | -| [size](./firestore_.querysnapshot.md#querysnapshotsize) | | number | The number of documents in the QuerySnapshot. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [docChanges(options)](./firestore_.querysnapshot.md#querysnapshotdocchanges) | | Returns an array of the documents changes since the last snapshot. If this is the first snapshot, all documents will be in the list as 'added' changes. | -| [forEach(callback, thisArg)](./firestore_.querysnapshot.md#querysnapshotforeach) | | Enumerates all of the documents in the QuerySnapshot. | - -## QuerySnapshot.docs - -An array of all the documents in the `QuerySnapshot`. - -Signature: - -```typescript -get docs(): Array>; -``` - -## QuerySnapshot.empty - -True if there are no documents in the `QuerySnapshot`. - -Signature: - -```typescript -get empty(): boolean; -``` - -## QuerySnapshot.metadata - -Metadata about this snapshot, concerning its source and if it has local modifications. - -Signature: - -```typescript -readonly metadata: SnapshotMetadata; -``` - -## QuerySnapshot.query - -The query on which you called `get` or `onSnapshot` in order to get this `QuerySnapshot`. - -Signature: - -```typescript -readonly query: Query; -``` - -## QuerySnapshot.size - -The number of documents in the `QuerySnapshot`. - -Signature: - -```typescript -get size(): number; -``` - -## QuerySnapshot.docChanges() - -Returns an array of the documents changes since the last snapshot. If this is the first snapshot, all documents will be in the list as 'added' changes. - -Signature: - -```typescript -docChanges(options?: SnapshotListenOptions): Array>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| options | [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | SnapshotListenOptions that control whether metadata-only changes (i.e. only DocumentSnapshot.metadata changed) should trigger snapshot events. | - -Returns: - -Array<[DocumentChange](./firestore_.documentchange.md#documentchange_interface)<T>> - -## QuerySnapshot.forEach() - -Enumerates all of the documents in the `QuerySnapshot`. - -Signature: - -```typescript -forEach(callback: (result: QueryDocumentSnapshot) => void, thisArg?: unknown): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| callback | (result: [QueryDocumentSnapshot](./firestore_.querydocumentsnapshot.md#querydocumentsnapshot_class)<T>) => void | A callback to be called with a QueryDocumentSnapshot for each document in the snapshot. | -| thisArg | unknown | The this binding for the callback. | - -Returns: - -void - diff --git a/docs-devsite/firestore_.querystartatconstraint.md b/docs-devsite/firestore_.querystartatconstraint.md deleted file mode 100644 index edad47f66ee..00000000000 --- a/docs-devsite/firestore_.querystartatconstraint.md +++ /dev/null @@ -1,36 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryStartAtConstraint class -A `QueryStartAtConstraint` is used to exclude documents from the start of a result set returned by a Firestore query. `QueryStartAtConstraint`s are created by invoking [startAt()](./firestore_.md#startat) or [startAfter()](./firestore_.md#startafter) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryStartAtConstraint`. - -Signature: - -```typescript -export declare class QueryStartAtConstraint extends QueryConstraint -``` -Extends: [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_.querystartatconstraint.md#querystartatconstrainttype) | | 'startAt' \| 'startAfter' | The type of this query constraint | - -## QueryStartAtConstraint.type - -The type of this query constraint - -Signature: - -```typescript -readonly type: 'startAt' | 'startAfter'; -``` diff --git a/docs-devsite/firestore_.snapshotlistenoptions.md b/docs-devsite/firestore_.snapshotlistenoptions.md deleted file mode 100644 index dba8308fc02..00000000000 --- a/docs-devsite/firestore_.snapshotlistenoptions.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# SnapshotListenOptions interface -An options object that can be passed to [onSnapshot()](./firestore_.md#onsnapshot) and [QuerySnapshot.docChanges()](./firestore_.querysnapshot.md#querysnapshotdocchanges) to control which types of changes to include in the result set. - -Signature: - -```typescript -export declare interface SnapshotListenOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [includeMetadataChanges](./firestore_.snapshotlistenoptions.md#snapshotlistenoptionsincludemetadatachanges) | boolean | Include a change even if only the metadata of the query or of a document changed. Default is false. | - -## SnapshotListenOptions.includeMetadataChanges - -Include a change even if only the metadata of the query or of a document changed. Default is false. - -Signature: - -```typescript -readonly includeMetadataChanges?: boolean; -``` diff --git a/docs-devsite/firestore_.snapshotmetadata.md b/docs-devsite/firestore_.snapshotmetadata.md deleted file mode 100644 index 6f062ed1c92..00000000000 --- a/docs-devsite/firestore_.snapshotmetadata.md +++ /dev/null @@ -1,75 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# SnapshotMetadata class -Metadata about a snapshot, describing the state of the snapshot. - -Signature: - -```typescript -export declare class SnapshotMetadata -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [fromCache](./firestore_.snapshotmetadata.md#snapshotmetadatafromcache) | | boolean | True if the snapshot was created from cached data rather than guaranteed up-to-date server data. If your listener has opted into metadata updates (via SnapshotListenOptions) you will receive another snapshot with fromCache set to false once the client has received up-to-date data from the backend. | -| [hasPendingWrites](./firestore_.snapshotmetadata.md#snapshotmetadatahaspendingwrites) | | boolean | True if the snapshot contains the result of local writes (for example set() or update() calls) that have not yet been committed to the backend. If your listener has opted into metadata updates (via SnapshotListenOptions) you will receive another snapshot with hasPendingWrites equal to false once the writes have been committed to the backend. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [isEqual(other)](./firestore_.snapshotmetadata.md#snapshotmetadataisequal) | | Returns true if this SnapshotMetadata is equal to the provided one. | - -## SnapshotMetadata.fromCache - -True if the snapshot was created from cached data rather than guaranteed up-to-date server data. If your listener has opted into metadata updates (via `SnapshotListenOptions`) you will receive another snapshot with `fromCache` set to false once the client has received up-to-date data from the backend. - -Signature: - -```typescript -readonly fromCache: boolean; -``` - -## SnapshotMetadata.hasPendingWrites - -True if the snapshot contains the result of local writes (for example `set()` or `update()` calls) that have not yet been committed to the backend. If your listener has opted into metadata updates (via `SnapshotListenOptions`) you will receive another snapshot with `hasPendingWrites` equal to false once the writes have been committed to the backend. - -Signature: - -```typescript -readonly hasPendingWrites: boolean; -``` - -## SnapshotMetadata.isEqual() - -Returns true if this `SnapshotMetadata` is equal to the provided one. - -Signature: - -```typescript -isEqual(other: SnapshotMetadata): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| other | [SnapshotMetadata](./firestore_.snapshotmetadata.md#snapshotmetadata_class) | The SnapshotMetadata to compare against. | - -Returns: - -boolean - -true if this `SnapshotMetadata` is equal to the provided one. - diff --git a/docs-devsite/firestore_.snapshotoptions.md b/docs-devsite/firestore_.snapshotoptions.md deleted file mode 100644 index e7ccd715552..00000000000 --- a/docs-devsite/firestore_.snapshotoptions.md +++ /dev/null @@ -1,41 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# SnapshotOptions interface -Options that configure how data is retrieved from a `DocumentSnapshot` (for example the desired behavior for server timestamps that have not yet been set to their final value). - -Signature: - -```typescript -export declare interface SnapshotOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [serverTimestamps](./firestore_.snapshotoptions.md#snapshotoptionsservertimestamps) | 'estimate' \| 'previous' \| 'none' | If set, controls the return value for server timestamps that have not yet been set to their final value.By specifying 'estimate', pending server timestamps return an estimate based on the local clock. This estimate will differ from the final value and cause these values to change once the server result becomes available.By specifying 'previous', pending timestamps will be ignored and return their previous value instead.If omitted or set to 'none', null will be returned by default until the server value becomes available. | - -## SnapshotOptions.serverTimestamps - -If set, controls the return value for server timestamps that have not yet been set to their final value. - -By specifying 'estimate', pending server timestamps return an estimate based on the local clock. This estimate will differ from the final value and cause these values to change once the server result becomes available. - -By specifying 'previous', pending timestamps will be ignored and return their previous value instead. - -If omitted or set to 'none', `null` will be returned by default until the server value becomes available. - -Signature: - -```typescript -readonly serverTimestamps?: 'estimate' | 'previous' | 'none'; -``` diff --git a/docs-devsite/firestore_.timestamp.md b/docs-devsite/firestore_.timestamp.md deleted file mode 100644 index ef75f07fdd5..00000000000 --- a/docs-devsite/firestore_.timestamp.md +++ /dev/null @@ -1,243 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Timestamp class -A `Timestamp` represents a point in time independent of any time zone or calendar, represented as seconds and fractions of seconds at nanosecond resolution in UTC Epoch time. - -It is encoded using the Proleptic Gregorian Calendar which extends the Gregorian calendar backwards to year one. It is encoded assuming all minutes are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. - -For examples and further specifications, refer to the [Timestamp definition](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto). - -Signature: - -```typescript -export declare class Timestamp -``` - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(seconds, nanoseconds)](./firestore_.timestamp.md#timestampconstructor) | | Creates a new timestamp. | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [nanoseconds](./firestore_.timestamp.md#timestampnanoseconds) | | number | The fractions of a second at nanosecond resolution.\* | -| [seconds](./firestore_.timestamp.md#timestampseconds) | | number | The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [fromDate(date)](./firestore_.timestamp.md#timestampfromdate) | static | Creates a new timestamp from the given date. | -| [fromMillis(milliseconds)](./firestore_.timestamp.md#timestampfrommillis) | static | Creates a new timestamp from the given number of milliseconds. | -| [isEqual(other)](./firestore_.timestamp.md#timestampisequal) | | Returns true if this Timestamp is equal to the provided one. | -| [now()](./firestore_.timestamp.md#timestampnow) | static | Creates a new timestamp with the current date, with millisecond precision. | -| [toDate()](./firestore_.timestamp.md#timestamptodate) | | Converts a Timestamp to a JavaScript Date object. This conversion causes a loss of precision since Date objects only support millisecond precision. | -| [toJSON()](./firestore_.timestamp.md#timestamptojson) | | Returns a JSON-serializable representation of this Timestamp. | -| [toMillis()](./firestore_.timestamp.md#timestamptomillis) | | Converts a Timestamp to a numeric timestamp (in milliseconds since epoch). This operation causes a loss of precision. | -| [toString()](./firestore_.timestamp.md#timestamptostring) | | Returns a textual representation of this Timestamp. | -| [valueOf()](./firestore_.timestamp.md#timestampvalueof) | | Converts this object to a primitive string, which allows Timestamp objects to be compared using the >, <=, >= and > operators. | - -## Timestamp.(constructor) - -Creates a new timestamp. - -Signature: - -```typescript -constructor( - seconds: number, - nanoseconds: number); -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| seconds | number | The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive. | -| nanoseconds | number | The non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanoseconds values that count forward in time. Must be from 0 to 999,999,999 inclusive. | - -## Timestamp.nanoseconds - -The fractions of a second at nanosecond resolution.\* - -Signature: - -```typescript -readonly nanoseconds: number; -``` - -## Timestamp.seconds - -The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. - -Signature: - -```typescript -readonly seconds: number; -``` - -## Timestamp.fromDate() - -Creates a new timestamp from the given date. - -Signature: - -```typescript -static fromDate(date: Date): Timestamp; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| date | Date | The date to initialize the Timestamp from. | - -Returns: - -[Timestamp](./firestore_.timestamp.md#timestamp_class) - -A new `Timestamp` representing the same point in time as the given date. - -## Timestamp.fromMillis() - -Creates a new timestamp from the given number of milliseconds. - -Signature: - -```typescript -static fromMillis(milliseconds: number): Timestamp; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| milliseconds | number | Number of milliseconds since Unix epoch 1970-01-01T00:00:00Z. | - -Returns: - -[Timestamp](./firestore_.timestamp.md#timestamp_class) - -A new `Timestamp` representing the same point in time as the given number of milliseconds. - -## Timestamp.isEqual() - -Returns true if this `Timestamp` is equal to the provided one. - -Signature: - -```typescript -isEqual(other: Timestamp): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| other | [Timestamp](./firestore_.timestamp.md#timestamp_class) | The Timestamp to compare against. | - -Returns: - -boolean - -true if this `Timestamp` is equal to the provided one. - -## Timestamp.now() - -Creates a new timestamp with the current date, with millisecond precision. - -Signature: - -```typescript -static now(): Timestamp; -``` -Returns: - -[Timestamp](./firestore_.timestamp.md#timestamp_class) - -a new timestamp representing the current date. - -## Timestamp.toDate() - -Converts a `Timestamp` to a JavaScript `Date` object. This conversion causes a loss of precision since `Date` objects only support millisecond precision. - -Signature: - -```typescript -toDate(): Date; -``` -Returns: - -Date - -JavaScript `Date` object representing the same point in time as this `Timestamp`, with millisecond precision. - -## Timestamp.toJSON() - -Returns a JSON-serializable representation of this `Timestamp`. - -Signature: - -```typescript -toJSON(): { - seconds: number; - nanoseconds: number; - }; -``` -Returns: - -{ seconds: number; nanoseconds: number; } - -## Timestamp.toMillis() - -Converts a `Timestamp` to a numeric timestamp (in milliseconds since epoch). This operation causes a loss of precision. - -Signature: - -```typescript -toMillis(): number; -``` -Returns: - -number - -The point in time corresponding to this timestamp, represented as the number of milliseconds since Unix epoch 1970-01-01T00:00:00Z. - -## Timestamp.toString() - -Returns a textual representation of this `Timestamp`. - -Signature: - -```typescript -toString(): string; -``` -Returns: - -string - -## Timestamp.valueOf() - -Converts this object to a primitive string, which allows `Timestamp` objects to be compared using the `>`, `<=`, `>=` and `>` operators. - -Signature: - -```typescript -valueOf(): string; -``` -Returns: - -string - diff --git a/docs-devsite/firestore_.transaction.md b/docs-devsite/firestore_.transaction.md deleted file mode 100644 index 24f0690bea4..00000000000 --- a/docs-devsite/firestore_.transaction.md +++ /dev/null @@ -1,190 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Transaction class -A reference to a transaction. - -The `Transaction` object passed to a transaction's `updateFunction` provides the methods to read and write data within the transaction context. See [runTransaction()](./firestore_.md#runtransaction). - -Signature: - -```typescript -export declare class Transaction -``` - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [delete(documentRef)](./firestore_.transaction.md#transactiondelete) | | Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). | -| [get(documentRef)](./firestore_.transaction.md#transactionget) | | Reads the document referenced by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). | -| [set(documentRef, data)](./firestore_.transaction.md#transactionset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. | -| [set(documentRef, data, options)](./firestore_.transaction.md#transactionset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document. | -| [update(documentRef, data)](./firestore_.transaction.md#transactionupdate) | | Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. | -| [update(documentRef, field, value, moreFieldsAndValues)](./firestore_.transaction.md#transactionupdate) | | Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist.Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects. | - -## Transaction.delete() - -Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). - -Signature: - -```typescript -delete(documentRef: DocumentReference): this; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to the document to be deleted. | - -Returns: - -this - -This `Transaction` instance. Used for chaining method calls. - -## Transaction.get() - -Reads the document referenced by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). - -Signature: - -```typescript -get(documentRef: DocumentReference): Promise>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be read. | - -Returns: - -Promise<[DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>> - -A `DocumentSnapshot` with the read data. - -## Transaction.set() - -Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. - -Signature: - -```typescript -set(documentRef: DocumentReference, data: WithFieldValue): this; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | -| data | [WithFieldValue](./firestore_.md#withfieldvalue)<T> | An object of the fields and values for the document. | - -Returns: - -this - -This `Transaction` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not a valid Firestore document. - -## Transaction.set() - -Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. - -Signature: - -```typescript -set(documentRef: DocumentReference, data: PartialWithFieldValue, options: SetOptions): this; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | -| data | [PartialWithFieldValue](./firestore_.md#partialwithfieldvalue)<T> | An object of the fields and values for the document. | -| options | [SetOptions](./firestore_.md#setoptions) | An object to configure the set behavior. | - -Returns: - -this - -This `Transaction` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not a valid Firestore document. - -## Transaction.update() - -Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. - -Signature: - -```typescript -update(documentRef: DocumentReference, data: UpdateData): this; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be updated. | -| data | [UpdateData](./firestore_.md#updatedata)<T> | An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document. | - -Returns: - -this - -This `Transaction` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not valid Firestore data. - -## Transaction.update() - -Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. - -Nested fields can be updated by providing dot-separated field path strings or by providing `FieldPath` objects. - -Signature: - -```typescript -update(documentRef: DocumentReference, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): this; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to the document to be updated. | -| field | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The first field to update. | -| value | unknown | The first value. | -| moreFieldsAndValues | unknown\[\] | Additional key/value pairs. | - -Returns: - -this - -This `Transaction` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not valid Firestore data. - diff --git a/docs-devsite/firestore_.transactionoptions.md b/docs-devsite/firestore_.transactionoptions.md deleted file mode 100644 index 1e7a5aedd28..00000000000 --- a/docs-devsite/firestore_.transactionoptions.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# TransactionOptions interface -Options to customize transaction behavior. - -Signature: - -```typescript -export declare interface TransactionOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [maxAttempts](./firestore_.transactionoptions.md#transactionoptionsmaxattempts) | number | Maximum number of attempts to commit, after which transaction fails. Default is 5. | - -## TransactionOptions.maxAttempts - -Maximum number of attempts to commit, after which transaction fails. Default is 5. - -Signature: - -```typescript -readonly maxAttempts?: number; -``` diff --git a/docs-devsite/firestore_.unsubscribe.md b/docs-devsite/firestore_.unsubscribe.md deleted file mode 100644 index 8bafb4f9ee8..00000000000 --- a/docs-devsite/firestore_.unsubscribe.md +++ /dev/null @@ -1,19 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Unsubscribe interface -A function returned by `onSnapshot()` that removes the listener when invoked. - -Signature: - -```typescript -export declare interface Unsubscribe -``` diff --git a/docs-devsite/firestore_.writebatch.md b/docs-devsite/firestore_.writebatch.md deleted file mode 100644 index 878cb66810a..00000000000 --- a/docs-devsite/firestore_.writebatch.md +++ /dev/null @@ -1,181 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# WriteBatch class -A write batch, used to perform multiple writes as a single atomic unit. - -A `WriteBatch` object can be acquired by calling [writeBatch()](./firestore_.md#writebatch). It provides methods for adding writes to the write batch. None of the writes will be committed (or visible locally) until [WriteBatch.commit()](./firestore_.writebatch.md#writebatchcommit) is called. - -Signature: - -```typescript -export declare class WriteBatch -``` - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [commit()](./firestore_.writebatch.md#writebatchcommit) | | Commits all of the writes in this write batch as a single atomic unit.The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | -| [delete(documentRef)](./firestore_.writebatch.md#writebatchdelete) | | Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). | -| [set(documentRef, data)](./firestore_.writebatch.md#writebatchset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. | -| [set(documentRef, data, options)](./firestore_.writebatch.md#writebatchset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document. | -| [update(documentRef, data)](./firestore_.writebatch.md#writebatchupdate) | | Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. | -| [update(documentRef, field, value, moreFieldsAndValues)](./firestore_.writebatch.md#writebatchupdate) | | Updates fields in the document referred to by this [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist.Nested fields can be update by providing dot-separated field path strings or by providing FieldPath objects. | - -## WriteBatch.commit() - -Commits all of the writes in this write batch as a single atomic unit. - -The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. - -Signature: - -```typescript -commit(): Promise; -``` -Returns: - -Promise<void> - -A `Promise` resolved once all of the writes in the batch have been successfully written to the backend as an atomic unit (note that it won't resolve while you're offline). - -## WriteBatch.delete() - -Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). - -Signature: - -```typescript -delete(documentRef: DocumentReference): WriteBatch; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to the document to be deleted. | - -Returns: - -[WriteBatch](./firestore_.writebatch.md#writebatch_class) - -This `WriteBatch` instance. Used for chaining method calls. - -## WriteBatch.set() - -Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. - -Signature: - -```typescript -set(documentRef: DocumentReference, data: WithFieldValue): WriteBatch; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | -| data | [WithFieldValue](./firestore_.md#withfieldvalue)<T> | An object of the fields and values for the document. | - -Returns: - -[WriteBatch](./firestore_.writebatch.md#writebatch_class) - -This `WriteBatch` instance. Used for chaining method calls. - -## WriteBatch.set() - -Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. - -Signature: - -```typescript -set(documentRef: DocumentReference, data: PartialWithFieldValue, options: SetOptions): WriteBatch; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | -| data | [PartialWithFieldValue](./firestore_.md#partialwithfieldvalue)<T> | An object of the fields and values for the document. | -| options | [SetOptions](./firestore_.md#setoptions) | An object to configure the set behavior. | - -Returns: - -[WriteBatch](./firestore_.writebatch.md#writebatch_class) - -This `WriteBatch` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not a valid Firestore document. - -## WriteBatch.update() - -Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. - -Signature: - -```typescript -update(documentRef: DocumentReference, data: UpdateData): WriteBatch; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be updated. | -| data | [UpdateData](./firestore_.md#updatedata)<T> | An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document. | - -Returns: - -[WriteBatch](./firestore_.writebatch.md#writebatch_class) - -This `WriteBatch` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not valid Firestore data. - -## WriteBatch.update() - -Updates fields in the document referred to by this [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. - -Nested fields can be update by providing dot-separated field path strings or by providing `FieldPath` objects. - -Signature: - -```typescript -update(documentRef: DocumentReference, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): WriteBatch; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to the document to be updated. | -| field | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The first field to update. | -| value | unknown | The first value. | -| moreFieldsAndValues | unknown\[\] | Additional key value pairs. | - -Returns: - -[WriteBatch](./firestore_.writebatch.md#writebatch_class) - -This `WriteBatch` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not valid Firestore data. - diff --git a/docs-devsite/firestore_lite.aggregatefield.md b/docs-devsite/firestore_lite.aggregatefield.md deleted file mode 100644 index 952b60c9d80..00000000000 --- a/docs-devsite/firestore_lite.aggregatefield.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AggregateField class -Represents an aggregation that can be performed by Firestore. - -Signature: - -```typescript -export declare class AggregateField -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_lite.aggregatefield.md#aggregatefieldtype) | | string | A type string to uniquely identify instances of this class. | - -## AggregateField.type - -A type string to uniquely identify instances of this class. - -Signature: - -```typescript -type: string; -``` diff --git a/docs-devsite/firestore_lite.aggregatequerysnapshot.md b/docs-devsite/firestore_lite.aggregatequerysnapshot.md deleted file mode 100644 index 4b5d3120ba3..00000000000 --- a/docs-devsite/firestore_lite.aggregatequerysnapshot.md +++ /dev/null @@ -1,70 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AggregateQuerySnapshot class -The results of executing an aggregation query. - -Signature: - -```typescript -export declare class AggregateQuerySnapshot -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [query](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshotquery) | | [Query](./firestore_lite.query.md#query_class)<unknown> | The underlying query over which the aggregations recorded in this AggregateQuerySnapshot were performed. | -| [type](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshottype) | | (not declared) | A type string to uniquely identify instances of this class. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [data()](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshotdata) | | Returns the results of the aggregations performed over the underlying query.The keys of the returned object will be the same as those of the AggregateSpec object specified to the aggregation method, and the values will be the corresponding aggregation result. | - -## AggregateQuerySnapshot.query - -The underlying query over which the aggregations recorded in this `AggregateQuerySnapshot` were performed. - -Signature: - -```typescript -readonly query: Query; -``` - -## AggregateQuerySnapshot.type - -A type string to uniquely identify instances of this class. - -Signature: - -```typescript -readonly type = "AggregateQuerySnapshot"; -``` - -## AggregateQuerySnapshot.data() - -Returns the results of the aggregations performed over the underlying query. - -The keys of the returned object will be the same as those of the `AggregateSpec` object specified to the aggregation method, and the values will be the corresponding aggregation result. - -Signature: - -```typescript -data(): AggregateSpecData; -``` -Returns: - -[AggregateSpecData](./firestore_lite.md#aggregatespecdata)<T> - -The results of the aggregations performed over the underlying query. - diff --git a/docs-devsite/firestore_lite.aggregatespec.md b/docs-devsite/firestore_lite.aggregatespec.md deleted file mode 100644 index be06b6941f3..00000000000 --- a/docs-devsite/firestore_lite.aggregatespec.md +++ /dev/null @@ -1,19 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# AggregateSpec interface -A type whose property values are all `AggregateField` objects. - -Signature: - -```typescript -export declare interface AggregateSpec -``` diff --git a/docs-devsite/firestore_lite.bytes.md b/docs-devsite/firestore_lite.bytes.md deleted file mode 100644 index 8dec3bdd201..00000000000 --- a/docs-devsite/firestore_lite.bytes.md +++ /dev/null @@ -1,138 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Bytes class -An immutable object representing an array of bytes. - -Signature: - -```typescript -export declare class Bytes -``` - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [fromBase64String(base64)](./firestore_lite.bytes.md#bytesfrombase64string) | static | Creates a new Bytes object from the given Base64 string, converting it to bytes. | -| [fromUint8Array(array)](./firestore_lite.bytes.md#bytesfromuint8array) | static | Creates a new Bytes object from the given Uint8Array. | -| [isEqual(other)](./firestore_lite.bytes.md#bytesisequal) | | Returns true if this Bytes object is equal to the provided one. | -| [toBase64()](./firestore_lite.bytes.md#bytestobase64) | | Returns the underlying bytes as a Base64-encoded string. | -| [toString()](./firestore_lite.bytes.md#bytestostring) | | Returns a string representation of the Bytes object. | -| [toUint8Array()](./firestore_lite.bytes.md#bytestouint8array) | | Returns the underlying bytes in a new Uint8Array. | - -## Bytes.fromBase64String() - -Creates a new `Bytes` object from the given Base64 string, converting it to bytes. - -Signature: - -```typescript -static fromBase64String(base64: string): Bytes; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| base64 | string | The Base64 string used to create the Bytes object. | - -Returns: - -[Bytes](./firestore_lite.bytes.md#bytes_class) - -## Bytes.fromUint8Array() - -Creates a new `Bytes` object from the given Uint8Array. - -Signature: - -```typescript -static fromUint8Array(array: Uint8Array): Bytes; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| array | Uint8Array | The Uint8Array used to create the Bytes object. | - -Returns: - -[Bytes](./firestore_lite.bytes.md#bytes_class) - -## Bytes.isEqual() - -Returns true if this `Bytes` object is equal to the provided one. - -Signature: - -```typescript -isEqual(other: Bytes): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| other | [Bytes](./firestore_lite.bytes.md#bytes_class) | The Bytes object to compare against. | - -Returns: - -boolean - -true if this `Bytes` object is equal to the provided one. - -## Bytes.toBase64() - -Returns the underlying bytes as a Base64-encoded string. - -Signature: - -```typescript -toBase64(): string; -``` -Returns: - -string - -The Base64-encoded string created from the `Bytes` object. - -## Bytes.toString() - -Returns a string representation of the `Bytes` object. - -Signature: - -```typescript -toString(): string; -``` -Returns: - -string - -A string representation of the `Bytes` object. - -## Bytes.toUint8Array() - -Returns the underlying bytes in a new `Uint8Array`. - -Signature: - -```typescript -toUint8Array(): Uint8Array; -``` -Returns: - -Uint8Array - -The Uint8Array created from the `Bytes` object. - diff --git a/docs-devsite/firestore_lite.collectionreference.md b/docs-devsite/firestore_lite.collectionreference.md deleted file mode 100644 index d446560a02f..00000000000 --- a/docs-devsite/firestore_lite.collectionreference.md +++ /dev/null @@ -1,121 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# CollectionReference class -A `CollectionReference` object can be used for adding documents, getting document references, and querying for documents (using [query()](./firestore_.md#query)). - -Signature: - -```typescript -export declare class CollectionReference extends Query -``` -Extends: [Query](./firestore_lite.query.md#query_class)<T> - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [id](./firestore_lite.collectionreference.md#collectionreferenceid) | | string | The collection's identifier. | -| [parent](./firestore_lite.collectionreference.md#collectionreferenceparent) | | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> \| null | A reference to the containing DocumentReference if this is a subcollection. If this isn't a subcollection, the reference is null. | -| [path](./firestore_lite.collectionreference.md#collectionreferencepath) | | string | A string representing the path of the referenced collection (relative to the root of the database). | -| [type](./firestore_lite.collectionreference.md#collectionreferencetype) | | (not declared) | The type of this Firestore reference. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [withConverter(converter)](./firestore_lite.collectionreference.md#collectionreferencewithconverter) | | Applies a custom data converter to this CollectionReference, allowing you to use your own custom model objects with Firestore. When you call [addDoc()](./firestore_.md#adddoc) with the returned CollectionReference instance, the provided converter will convert between Firestore data and your custom type U. | -| [withConverter(converter)](./firestore_lite.collectionreference.md#collectionreferencewithconverter) | | Removes the current converter. | - -## CollectionReference.id - -The collection's identifier. - -Signature: - -```typescript -get id(): string; -``` - -## CollectionReference.parent - -A reference to the containing `DocumentReference` if this is a subcollection. If this isn't a subcollection, the reference is null. - -Signature: - -```typescript -get parent(): DocumentReference | null; -``` - -## CollectionReference.path - -A string representing the path of the referenced collection (relative to the root of the database). - -Signature: - -```typescript -get path(): string; -``` - -## CollectionReference.type - -The type of this Firestore reference. - -Signature: - -```typescript -readonly type = "collection"; -``` - -## CollectionReference.withConverter() - -Applies a custom data converter to this `CollectionReference`, allowing you to use your own custom model objects with Firestore. When you call [addDoc()](./firestore_.md#adddoc) with the returned `CollectionReference` instance, the provided converter will convert between Firestore data and your custom type `U`. - -Signature: - -```typescript -withConverter(converter: FirestoreDataConverter): CollectionReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| converter | [FirestoreDataConverter](./firestore_lite.firestoredataconverter.md#firestoredataconverter_interface)<U> | Converts objects to and from Firestore. | - -Returns: - -[CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<U> - -A `CollectionReference` that uses the provided converter. - -## CollectionReference.withConverter() - -Removes the current converter. - -Signature: - -```typescript -withConverter(converter: null): CollectionReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| converter | null | null removes the current converter. | - -Returns: - -[CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> - -A `CollectionReference` that does not use a converter. - diff --git a/docs-devsite/firestore_lite.documentdata.md b/docs-devsite/firestore_lite.documentdata.md deleted file mode 100644 index 09b5eb64b48..00000000000 --- a/docs-devsite/firestore_lite.documentdata.md +++ /dev/null @@ -1,19 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# DocumentData interface -Document data (for use with [setDoc()](./firestore_lite.md#setdoc)) consists of fields mapped to values. - -Signature: - -```typescript -export declare interface DocumentData -``` diff --git a/docs-devsite/firestore_lite.documentreference.md b/docs-devsite/firestore_lite.documentreference.md deleted file mode 100644 index 0e307435949..00000000000 --- a/docs-devsite/firestore_lite.documentreference.md +++ /dev/null @@ -1,142 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# DocumentReference class -A `DocumentReference` refers to a document location in a Firestore database and can be used to write, read, or listen to the location. The document at the referenced location may or may not exist. - -Signature: - -```typescript -export declare class DocumentReference -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [converter](./firestore_lite.documentreference.md#documentreferenceconverter) | | [FirestoreDataConverter](./firestore_lite.firestoredataconverter.md#firestoredataconverter_interface)<T> \| null | If provided, the FirestoreDataConverter associated with this instance. | -| [firestore](./firestore_lite.documentreference.md#documentreferencefirestore) | | [Firestore](./firestore_lite.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance the document is in. This is useful for performing transactions, for example. | -| [id](./firestore_lite.documentreference.md#documentreferenceid) | | string | The document's identifier within its collection. | -| [parent](./firestore_lite.documentreference.md#documentreferenceparent) | | [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | The collection this DocumentReference belongs to. | -| [path](./firestore_lite.documentreference.md#documentreferencepath) | | string | A string representing the path of the referenced document (relative to the root of the database). | -| [type](./firestore_lite.documentreference.md#documentreferencetype) | | (not declared) | The type of this Firestore reference. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [withConverter(converter)](./firestore_lite.documentreference.md#documentreferencewithconverter) | | Applies a custom data converter to this DocumentReference, allowing you to use your own custom model objects with Firestore. When you call [setDoc()](./firestore_lite.md#setdoc), [getDoc()](./firestore_lite.md#getdoc), etc. with the returned DocumentReference instance, the provided converter will convert between Firestore data and your custom type U. | -| [withConverter(converter)](./firestore_lite.documentreference.md#documentreferencewithconverter) | | Removes the current converter. | - -## DocumentReference.converter - -If provided, the `FirestoreDataConverter` associated with this instance. - -Signature: - -```typescript -readonly converter: FirestoreDataConverter | null; -``` - -## DocumentReference.firestore - -The [Firestore](./firestore_.firestore.md#firestore_class) instance the document is in. This is useful for performing transactions, for example. - -Signature: - -```typescript -readonly firestore: Firestore; -``` - -## DocumentReference.id - -The document's identifier within its collection. - -Signature: - -```typescript -get id(): string; -``` - -## DocumentReference.parent - -The collection this `DocumentReference` belongs to. - -Signature: - -```typescript -get parent(): CollectionReference; -``` - -## DocumentReference.path - -A string representing the path of the referenced document (relative to the root of the database). - -Signature: - -```typescript -get path(): string; -``` - -## DocumentReference.type - -The type of this Firestore reference. - -Signature: - -```typescript -readonly type = "document"; -``` - -## DocumentReference.withConverter() - -Applies a custom data converter to this `DocumentReference`, allowing you to use your own custom model objects with Firestore. When you call [setDoc()](./firestore_lite.md#setdoc), [getDoc()](./firestore_lite.md#getdoc), etc. with the returned `DocumentReference` instance, the provided converter will convert between Firestore data and your custom type `U`. - -Signature: - -```typescript -withConverter(converter: FirestoreDataConverter): DocumentReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| converter | [FirestoreDataConverter](./firestore_lite.firestoredataconverter.md#firestoredataconverter_interface)<U> | Converts objects to and from Firestore. | - -Returns: - -[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<U> - -A `DocumentReference` that uses the provided converter. - -## DocumentReference.withConverter() - -Removes the current converter. - -Signature: - -```typescript -withConverter(converter: null): DocumentReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| converter | null | null removes the current converter. | - -Returns: - -[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> - -A `DocumentReference` that does not use a converter. - diff --git a/docs-devsite/firestore_lite.documentsnapshot.md b/docs-devsite/firestore_lite.documentsnapshot.md deleted file mode 100644 index cfea1feb919..00000000000 --- a/docs-devsite/firestore_lite.documentsnapshot.md +++ /dev/null @@ -1,125 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# DocumentSnapshot class -A `DocumentSnapshot` contains data read from a document in your Firestore database. The data can be extracted with `.data()` or `.get()` to get a specific field. - -For a `DocumentSnapshot` that points to a non-existing document, any data access will return 'undefined'. You can use the `exists()` method to explicitly verify a document's existence. - -Signature: - -```typescript -export declare class DocumentSnapshot -``` - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)()](./firestore_lite.documentsnapshot.md#documentsnapshotconstructor) | | Constructs a new instance of the DocumentSnapshot class | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [id](./firestore_lite.documentsnapshot.md#documentsnapshotid) | | string | Property of the DocumentSnapshot that provides the document's ID. | -| [ref](./firestore_lite.documentsnapshot.md#documentsnapshotref) | | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | The DocumentReference for the document included in the DocumentSnapshot. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [data()](./firestore_lite.documentsnapshot.md#documentsnapshotdata) | | Retrieves all fields in the document as an Object. Returns undefined if the document doesn't exist. | -| [exists()](./firestore_lite.documentsnapshot.md#documentsnapshotexists) | | Signals whether or not the document at the snapshot's location exists. | -| [get(fieldPath)](./firestore_lite.documentsnapshot.md#documentsnapshotget) | | Retrieves the field specified by fieldPath. Returns undefined if the document or field doesn't exist. | - -## DocumentSnapshot.(constructor) - -Constructs a new instance of the `DocumentSnapshot` class - -Signature: - -```typescript -protected constructor(); -``` - -## DocumentSnapshot.id - -Property of the `DocumentSnapshot` that provides the document's ID. - -Signature: - -```typescript -get id(): string; -``` - -## DocumentSnapshot.ref - -The `DocumentReference` for the document included in the `DocumentSnapshot`. - -Signature: - -```typescript -get ref(): DocumentReference; -``` - -## DocumentSnapshot.data() - -Retrieves all fields in the document as an `Object`. Returns `undefined` if the document doesn't exist. - -Signature: - -```typescript -data(): T | undefined; -``` -Returns: - -T \| undefined - -An `Object` containing all fields in the document or `undefined` if the document doesn't exist. - -## DocumentSnapshot.exists() - -Signals whether or not the document at the snapshot's location exists. - -Signature: - -```typescript -exists(): this is QueryDocumentSnapshot; -``` -Returns: - -this is [QueryDocumentSnapshot](./firestore_lite.querydocumentsnapshot.md#querydocumentsnapshot_class)<T> - -true if the document exists. - -## DocumentSnapshot.get() - -Retrieves the field specified by `fieldPath`. Returns `undefined` if the document or field doesn't exist. - -Signature: - -```typescript -get(fieldPath: string | FieldPath): any; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldPath | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The path (for example 'foo' or 'foo.bar') to a specific field. | - -Returns: - -any - -The data at the specified field location or undefined if no such field exists in the document. - diff --git a/docs-devsite/firestore_lite.fieldpath.md b/docs-devsite/firestore_lite.fieldpath.md deleted file mode 100644 index ea449fc065b..00000000000 --- a/docs-devsite/firestore_lite.fieldpath.md +++ /dev/null @@ -1,72 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FieldPath class -A `FieldPath` refers to a field in a document. The path may consist of a single field name (referring to a top-level field in the document), or a list of field names (referring to a nested field in the document). - -Create a `FieldPath` by providing field names. If more than one field name is provided, the path will point to a nested field in a document. - -Signature: - -```typescript -export declare class FieldPath -``` - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(fieldNames)](./firestore_lite.fieldpath.md#fieldpathconstructor) | | Creates a FieldPath from the provided field names. If more than one field name is provided, the path will point to a nested field in a document. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [isEqual(other)](./firestore_lite.fieldpath.md#fieldpathisequal) | | Returns true if this FieldPath is equal to the provided one. | - -## FieldPath.(constructor) - -Creates a `FieldPath` from the provided field names. If more than one field name is provided, the path will point to a nested field in a document. - -Signature: - -```typescript -constructor(...fieldNames: string[]); -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldNames | string\[\] | A list of field names. | - -## FieldPath.isEqual() - -Returns true if this `FieldPath` is equal to the provided one. - -Signature: - -```typescript -isEqual(other: FieldPath): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| other | [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The FieldPath to compare against. | - -Returns: - -boolean - -true if this `FieldPath` is equal to the provided one. - diff --git a/docs-devsite/firestore_lite.fieldvalue.md b/docs-devsite/firestore_lite.fieldvalue.md deleted file mode 100644 index 454693c9771..00000000000 --- a/docs-devsite/firestore_lite.fieldvalue.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FieldValue class -Sentinel values that can be used when writing document fields with `set()` or `update()`. - -Signature: - -```typescript -export declare abstract class FieldValue -``` - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [isEqual(other)](./firestore_lite.fieldvalue.md#fieldvalueisequal) | | Compares FieldValues for equality. | - -## FieldValue.isEqual() - -Compares `FieldValue`s for equality. - -Signature: - -```typescript -abstract isEqual(other: FieldValue): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| other | [FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) | | - -Returns: - -boolean - diff --git a/docs-devsite/firestore_lite.firestore.md b/docs-devsite/firestore_lite.firestore.md deleted file mode 100644 index 2edac7aa130..00000000000 --- a/docs-devsite/firestore_lite.firestore.md +++ /dev/null @@ -1,68 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Firestore class -The Cloud Firestore service interface. - -Do not call this constructor directly. Instead, use [getFirestore()](./firestore_.md#getfirestore). - -Signature: - -```typescript -export declare class Firestore -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [app](./firestore_lite.firestore.md#firestoreapp) | | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this Firestore service instance. | -| [type](./firestore_lite.firestore.md#firestoretype) | | 'firestore-lite' \| 'firestore' | Whether it's a Firestore or Firestore Lite instance. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [toJSON()](./firestore_lite.firestore.md#firestoretojson) | | Returns a JSON-serializable representation of this Firestore instance. | - -## Firestore.app - -The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this `Firestore` service instance. - -Signature: - -```typescript -get app(): FirebaseApp; -``` - -## Firestore.type - -Whether it's a Firestore or Firestore Lite instance. - -Signature: - -```typescript -type: 'firestore-lite' | 'firestore'; -``` - -## Firestore.toJSON() - -Returns a JSON-serializable representation of this `Firestore` instance. - -Signature: - -```typescript -toJSON(): object; -``` -Returns: - -object - diff --git a/docs-devsite/firestore_lite.firestoredataconverter.md b/docs-devsite/firestore_lite.firestoredataconverter.md deleted file mode 100644 index 00510e0c22b..00000000000 --- a/docs-devsite/firestore_lite.firestoredataconverter.md +++ /dev/null @@ -1,130 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FirestoreDataConverter interface -Converter used by `withConverter()` to transform user objects of type `T` into Firestore data. - -Using the converter allows you to specify generic type arguments when storing and retrieving objects from Firestore. - -Signature: - -```typescript -export declare interface FirestoreDataConverter -``` - -## Methods - -| Method | Description | -| --- | --- | -| [fromFirestore(snapshot)](./firestore_lite.firestoredataconverter.md#firestoredataconverterfromfirestore) | Called by the Firestore SDK to convert Firestore data into an object of type T. You can access your data by calling: snapshot.data(). | -| [toFirestore(modelObject)](./firestore_lite.firestoredataconverter.md#firestoredataconvertertofirestore) | Called by the Firestore SDK to convert a custom model object of type T into a plain Javascript object (suitable for writing directly to the Firestore database). Used with [setDoc()](./firestore_lite.md#setdoc), and .The WithFieldValue<T> type extends T to also allow FieldValues such as [deleteField()](./firestore_.md#deletefield) to be used as property values. | -| [toFirestore(modelObject, options)](./firestore_lite.firestoredataconverter.md#firestoredataconvertertofirestore) | Called by the Firestore SDK to convert a custom model object of type T into a plain Javascript object (suitable for writing directly to the Firestore database). Used with [setDoc()](./firestore_lite.md#setdoc), and with merge:true or mergeFields.The PartialWithFieldValue<T> type extends Partial<T> to allow FieldValues such as [arrayUnion()](./firestore_.md#arrayunion) to be used as property values. It also supports nested Partial by allowing nested fields to be omitted. | - -## FirestoreDataConverter.fromFirestore() - -Called by the Firestore SDK to convert Firestore data into an object of type T. You can access your data by calling: `snapshot.data()`. - -Signature: - -```typescript -fromFirestore(snapshot: QueryDocumentSnapshot): T; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| snapshot | [QueryDocumentSnapshot](./firestore_lite.querydocumentsnapshot.md#querydocumentsnapshot_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> | A QueryDocumentSnapshot containing your data and metadata. | - -Returns: - -T - -## FirestoreDataConverter.toFirestore() - -Called by the Firestore SDK to convert a custom model object of type `T` into a plain Javascript object (suitable for writing directly to the Firestore database). Used with [setDoc()](./firestore_lite.md#setdoc), and . - -The `WithFieldValue` type extends `T` to also allow FieldValues such as [deleteField()](./firestore_.md#deletefield) to be used as property values. - -Signature: - -```typescript -toFirestore(modelObject: WithFieldValue): DocumentData; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| modelObject | [WithFieldValue](./firestore_lite.md#withfieldvalue)<T> | | - -Returns: - -[DocumentData](./firestore_lite.documentdata.md#documentdata_interface) - -## FirestoreDataConverter.toFirestore() - -Called by the Firestore SDK to convert a custom model object of type `T` into a plain Javascript object (suitable for writing directly to the Firestore database). Used with [setDoc()](./firestore_lite.md#setdoc), and with `merge:true` or `mergeFields`. - -The `PartialWithFieldValue` type extends `Partial` to allow FieldValues such as [arrayUnion()](./firestore_.md#arrayunion) to be used as property values. It also supports nested `Partial` by allowing nested fields to be omitted. - -Signature: - -```typescript -toFirestore(modelObject: PartialWithFieldValue, options: SetOptions): DocumentData; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| modelObject | [PartialWithFieldValue](./firestore_lite.md#partialwithfieldvalue)<T> | | -| options | [SetOptions](./firestore_lite.md#setoptions) | | - -Returns: - -[DocumentData](./firestore_lite.documentdata.md#documentdata_interface) - -### Example - - -```typescript -class Post { - constructor(readonly title: string, readonly author: string) {} - - toString(): string { - return this.title + ', by ' + this.author; - } -} - -const postConverter = { - toFirestore(post: WithFieldValue): DocumentData { - return {title: post.title, author: post.author}; - }, - fromFirestore(snapshot: QueryDocumentSnapshot): Post { - const data = snapshot.data(options)!; - return new Post(data.title, data.author); - } -}; - -const postSnap = await firebase.firestore() - .collection('posts') - .withConverter(postConverter) - .doc().get(); -const post = postSnap.data(); -if (post !== undefined) { - post.title; // string - post.toString(); // Should be defined - post.someNonExistentProperty; // TS error -} - -``` - diff --git a/docs-devsite/firestore_lite.firestoreerror.md b/docs-devsite/firestore_lite.firestoreerror.md deleted file mode 100644 index e3c6dd23029..00000000000 --- a/docs-devsite/firestore_lite.firestoreerror.md +++ /dev/null @@ -1,58 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FirestoreError class -An error returned by a Firestore operation. - -Signature: - -```typescript -export declare class FirestoreError extends FirebaseError -``` -Extends: [FirebaseError](./util.firebaseerror.md#firebaseerror_class) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [code](./firestore_lite.firestoreerror.md#firestoreerrorcode) | | [FirestoreErrorCode](./firestore_lite.md#firestoreerrorcode) | The backend error code associated with this error. | -| [message](./firestore_lite.firestoreerror.md#firestoreerrormessage) | | string | A custom error description. | -| [stack](./firestore_lite.firestoreerror.md#firestoreerrorstack) | | string | The stack of the error. | - -## FirestoreError.code - -The backend error code associated with this error. - -Signature: - -```typescript -readonly code: FirestoreErrorCode; -``` - -## FirestoreError.message - -A custom error description. - -Signature: - -```typescript -readonly message: string; -``` - -## FirestoreError.stack - -The stack of the error. - -Signature: - -```typescript -readonly stack?: string; -``` diff --git a/docs-devsite/firestore_lite.geopoint.md b/docs-devsite/firestore_lite.geopoint.md deleted file mode 100644 index 23576c41d8d..00000000000 --- a/docs-devsite/firestore_lite.geopoint.md +++ /dev/null @@ -1,117 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# GeoPoint class -An immutable object representing a geographic location in Firestore. The location is represented as latitude/longitude pair. - -Latitude values are in the range of \[-90, 90\]. Longitude values are in the range of \[-180, 180\]. - -Signature: - -```typescript -export declare class GeoPoint -``` - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(latitude, longitude)](./firestore_lite.geopoint.md#geopointconstructor) | | Creates a new immutable GeoPoint object with the provided latitude and longitude values. | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [latitude](./firestore_lite.geopoint.md#geopointlatitude) | | number | The latitude of this GeoPoint instance. | -| [longitude](./firestore_lite.geopoint.md#geopointlongitude) | | number | The longitude of this GeoPoint instance. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [isEqual(other)](./firestore_lite.geopoint.md#geopointisequal) | | Returns true if this GeoPoint is equal to the provided one. | -| [toJSON()](./firestore_lite.geopoint.md#geopointtojson) | | Returns a JSON-serializable representation of this GeoPoint. | - -## GeoPoint.(constructor) - -Creates a new immutable `GeoPoint` object with the provided latitude and longitude values. - -Signature: - -```typescript -constructor(latitude: number, longitude: number); -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| latitude | number | The latitude as number between -90 and 90. | -| longitude | number | The longitude as number between -180 and 180. | - -## GeoPoint.latitude - -The latitude of this `GeoPoint` instance. - -Signature: - -```typescript -get latitude(): number; -``` - -## GeoPoint.longitude - -The longitude of this `GeoPoint` instance. - -Signature: - -```typescript -get longitude(): number; -``` - -## GeoPoint.isEqual() - -Returns true if this `GeoPoint` is equal to the provided one. - -Signature: - -```typescript -isEqual(other: GeoPoint): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| other | [GeoPoint](./firestore_lite.geopoint.md#geopoint_class) | The GeoPoint to compare against. | - -Returns: - -boolean - -true if this `GeoPoint` is equal to the provided one. - -## GeoPoint.toJSON() - -Returns a JSON-serializable representation of this GeoPoint. - -Signature: - -```typescript -toJSON(): { - latitude: number; - longitude: number; - }; -``` -Returns: - -{ latitude: number; longitude: number; } - diff --git a/docs-devsite/firestore_lite.md b/docs-devsite/firestore_lite.md deleted file mode 100644 index 3754cda22b7..00000000000 --- a/docs-devsite/firestore_lite.md +++ /dev/null @@ -1,1443 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# @firebase/firestore/lite - -## Functions - -| Function | Description | -| --- | --- | -| function(app...) | -| [getFirestore(app)](./firestore_lite.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. | -| [initializeFirestore(app, settings)](./firestore_lite.md#initializefirestore) | Initializes a new instance of Cloud Firestore with the provided settings. Can only be called before any other functions, including [getFirestore()](./firestore_.md#getfirestore). If the custom settings are empty, this function is equivalent to calling [getFirestore()](./firestore_.md#getfirestore). | -| function(firestore...) | -| [collection(firestore, path, pathSegments)](./firestore_lite.md#collection) | Gets a CollectionReference instance that refers to the collection at the specified absolute path. | -| [collectionGroup(firestore, collectionId)](./firestore_lite.md#collectiongroup) | Creates and returns a new Query instance that includes all documents in the database that are contained in a collection or subcollection with the given collectionId. | -| [connectFirestoreEmulator(firestore, host, port, options)](./firestore_lite.md#connectfirestoreemulator) | Modify this instance to communicate with the Cloud Firestore emulator.Note: This must be called before this instance has been used to do any operations. | -| [doc(firestore, path, pathSegments)](./firestore_lite.md#doc) | Gets a DocumentReference instance that refers to the document at the specified absolute path. | -| [runTransaction(firestore, updateFunction, options)](./firestore_lite.md#runtransaction) | Executes the given updateFunction and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, Cloud Firestore retries the updateFunction. If it fails to commit after 5 attempts, the transaction fails.The maximum number of writes allowed in a single transaction is 500. | -| [terminate(firestore)](./firestore_lite.md#terminate) | Terminates the provided Firestore instance.After calling terminate() only the clearIndexedDbPersistence() functions may be used. Any other function will throw a FirestoreError. Termination does not cancel any pending writes, and any promises that are awaiting a response from the server will not be resolved.To restart after termination, create a new instance of Firestore with [getFirestore()](./firestore_.md#getfirestore).Note: Under normal circumstances, calling terminate() is not required. This function is useful only when you want to force this instance to release all of its resources or in combination with [clearIndexedDbPersistence()](./firestore_.md#clearindexeddbpersistence) to ensure that all local state is destroyed between test runs. | -| [writeBatch(firestore)](./firestore_lite.md#writebatch) | Creates a write batch, used for performing multiple writes as a single atomic operation. The maximum number of writes allowed in a single WriteBatch is 500.The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | -| function() | -| [deleteField()](./firestore_lite.md#deletefield) | Returns a sentinel for use with [updateDoc()](./firestore_lite.md#updatedoc) or [setDoc()](./firestore_lite.md#setdoc) with {merge: true} to mark a field for deletion. | -| [documentId()](./firestore_lite.md#documentid) | Returns a special sentinel FieldPath to refer to the ID of a document. It can be used in queries to sort or filter by the document ID. | -| [getFirestore()](./firestore_lite.md#getfirestore) | Returns the existing default [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. | -| [serverTimestamp()](./firestore_lite.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(elements...) | -| [arrayRemove(elements)](./firestore_lite.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_lite.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. | -| function(fieldPath...) | -| [orderBy(fieldPath, directionStr)](./firestore_lite.md#orderby) | Creates a [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class) that sorts the query result by the specified field, optionally in descending order instead of ascending.Note: Documents that do not contain the specified field will not be present in the query result. | -| [where(fieldPath, opStr, value)](./firestore_lite.md#where) | Creates a [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) that enforces that documents must contain the specified field and that the value should satisfy the relation constraint provided. | -| function(fieldValues...) | -| [endAt(fieldValues)](./firestore_lite.md#endat) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | -| [endBefore(fieldValues)](./firestore_lite.md#endbefore) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | -| [startAfter(fieldValues)](./firestore_lite.md#startafter) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | -| [startAt(fieldValues)](./firestore_lite.md#startat) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | -| function(left...) | -| [aggregateQuerySnapshotEqual(left, right)](./firestore_lite.md#aggregatequerysnapshotequal) | Compares two AggregateQuerySnapshot instances for equality.Two AggregateQuerySnapshot instances are considered "equal" if they have underlying queries that compare equal, and the same data. | -| [queryEqual(left, right)](./firestore_lite.md#queryequal) | Returns true if the provided queries point to the same collection and apply the same constraints. | -| [refEqual(left, right)](./firestore_lite.md#refequal) | Returns true if the provided references are equal. | -| [snapshotEqual(left, right)](./firestore_lite.md#snapshotequal) | Returns true if the provided snapshots are equal. | -| function(limit...) | -| [limit(limit)](./firestore_lite.md#limit) | Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the first matching documents. | -| [limitToLast(limit)](./firestore_lite.md#limittolast) | Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the last matching documents.You must specify at least one orderBy clause for limitToLast queries, otherwise an exception will be thrown during execution. | -| function(logLevel...) | -| [setLogLevel(logLevel)](./firestore_lite.md#setloglevel) | Sets the verbosity of Cloud Firestore logs (debug, error, or silent). | -| function(n...) | -| [increment(n)](./firestore_lite.md#increment) | 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 increment the field's current value by the given value.If either the operand or the current field value uses floating point precision, all arithmetic follows IEEE 754 semantics. If both values are integers, values outside of JavaScript's safe number range (Number.MIN_SAFE_INTEGER to Number.MAX_SAFE_INTEGER) are also subject to precision loss. Furthermore, once processed by the Firestore backend, all integer operations are capped between -2^63 and 2^63-1.If the current field value is not of type number, or if the field does not yet exist, the transformation sets the field to the given value. | -| function(query...) | -| [getCount(query)](./firestore_lite.md#getcount) | Calculates the number of documents in the result set of the given query, without actually downloading the documents.Using this function to count the documents is efficient because only the final count, not the documents' data, is downloaded. This function can even count the documents if the result set would be prohibitively large to download entirely (e.g. thousands of documents). | -| [getDocs(query)](./firestore_lite.md#getdocs) | Executes the query and returns the results as a [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class).All queries are executed directly by the server, even if the the query was previously executed. Recent modifications are only reflected in the retrieved results if they have already been applied by the backend. If the client is offline, the operation fails. To see previously cached result and local modifications, use the full Firestore SDK. | -| [query(query, queryConstraints)](./firestore_lite.md#query) | Creates a new immutable instance of [Query](./firestore_.query.md#query_class) that is extended to also include additional query constraints. | -| function(reference...) | -| [addDoc(reference, data)](./firestore_lite.md#adddoc) | Add a new document to specified CollectionReference with the given data, assigning it a document ID automatically.The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | -| [collection(reference, path, pathSegments)](./firestore_lite.md#collection) | Gets a CollectionReference instance that refers to a subcollection of reference at the the specified relative path. | -| [collection(reference, path, pathSegments)](./firestore_lite.md#collection) | Gets a CollectionReference instance that refers to a subcollection of reference at the the specified relative path. | -| [deleteDoc(reference)](./firestore_lite.md#deletedoc) | Deletes the document referred to by the specified DocumentReference.The deletion will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the delete fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | -| [doc(reference, path, pathSegments)](./firestore_lite.md#doc) | Gets a DocumentReference instance that refers to a document within reference at the specified relative path. If no path is specified, an automatically-generated unique ID will be used for the returned DocumentReference. | -| [doc(reference, path, pathSegments)](./firestore_lite.md#doc) | Gets a DocumentReference instance that refers to a document within reference at the specified relative path. | -| [getDoc(reference)](./firestore_lite.md#getdoc) | Reads the document referred to by the specified document reference.All documents are directly fetched from the server, even if the document was previously read or modified. Recent modifications are only reflected in the retrieved DocumentSnapshot if they have already been applied by the backend. If the client is offline, the read fails. If you like to use caching or see local modifications, please use the full Firestore SDK. | -| [setDoc(reference, data)](./firestore_lite.md#setdoc) | Writes to the document referred to by the specified DocumentReference. If the document does not yet exist, it will be created.The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | -| [setDoc(reference, data, options)](./firestore_lite.md#setdoc) | Writes to the document referred to by the specified DocumentReference. If the document does not yet exist, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document.The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | -| [updateDoc(reference, data)](./firestore_lite.md#updatedoc) | Updates fields in the document referred to by the specified DocumentReference. The update will fail if applied to a document that does not exist.The result of this update will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the update fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | -| [updateDoc(reference, field, value, moreFieldsAndValues)](./firestore_lite.md#updatedoc) | Updates fields in the document referred to by the specified DocumentReference The update will fail if applied to a document that does not exist.Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects.The result of this update will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the update fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | -| function(snapshot...) | -| [endAt(snapshot)](./firestore_lite.md#endat) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided document (inclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | -| [endBefore(snapshot)](./firestore_lite.md#endbefore) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | -| [startAfter(snapshot)](./firestore_lite.md#startafter) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | -| [startAt(snapshot)](./firestore_lite.md#startat) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of this query. | - -## Classes - -| Class | Description | -| --- | --- | -| [AggregateField](./firestore_lite.aggregatefield.md#aggregatefield_class) | Represents an aggregation that can be performed by Firestore. | -| [AggregateQuerySnapshot](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshot_class) | The results of executing an aggregation query. | -| [Bytes](./firestore_lite.bytes.md#bytes_class) | An immutable object representing an array of bytes. | -| [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class) | A CollectionReference object can be used for adding documents, getting document references, and querying for documents (using [query()](./firestore_.md#query)). | -| [DocumentReference](./firestore_lite.documentreference.md#documentreference_class) | A DocumentReference refers to a document location in a Firestore database and can be used to write, read, or listen to the location. The document at the referenced location may or may not exist. | -| [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class) | A DocumentSnapshot contains data read from a document in your Firestore database. The data can be extracted with .data() or .get(<field>) to get a specific field.For a DocumentSnapshot that points to a non-existing document, any data access will return 'undefined'. You can use the exists() method to explicitly verify a document's existence. | -| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | A FieldPath refers to a field in a document. The path may consist of a single field name (referring to a top-level field in the document), or a list of field names (referring to a nested field in the document).Create a FieldPath by providing field names. If more than one field name is provided, the path will point to a nested field in a document. | -| [FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) | Sentinel values that can be used when writing document fields with set() or update(). | -| [Firestore](./firestore_lite.firestore.md#firestore_class) | The Cloud Firestore service interface.Do not call this constructor directly. Instead, use [getFirestore()](./firestore_.md#getfirestore). | -| [FirestoreError](./firestore_lite.firestoreerror.md#firestoreerror_class) | An error returned by a Firestore operation. | -| [GeoPoint](./firestore_lite.geopoint.md#geopoint_class) | An immutable object representing a geographic location in Firestore. The location is represented as latitude/longitude pair.Latitude values are in the range of \[-90, 90\]. Longitude values are in the range of \[-180, 180\]. | -| [Query](./firestore_lite.query.md#query_class) | A Query refers to a query which you can read or listen to. You can also construct refined Query objects by adding filters and ordering. | -| [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) | A QueryConstraint is used to narrow the set of documents returned by a Firestore query. QueryConstraints are created by invoking [where()](./firestore_.md#where), [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit), [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryConstraint. | -| [QueryDocumentSnapshot](./firestore_lite.querydocumentsnapshot.md#querydocumentsnapshot_class) | A QueryDocumentSnapshot contains data read from a document in your Firestore database as part of a query. The document is guaranteed to exist and its data can be extracted with .data() or .get(<field>) to get a specific field.A QueryDocumentSnapshot offers the same API surface as a DocumentSnapshot. Since query results contain only existing documents, the exists property will always be true and data() will never return 'undefined'. | -| [QueryEndAtConstraint](./firestore_lite.queryendatconstraint.md#queryendatconstraint_class) | A QueryEndAtConstraint is used to exclude documents from the end of a result set returned by a Firestore query. QueryEndAtConstraints are created by invoking [endAt()](./firestore_.md#endat) or [endBefore()](./firestore_.md#endbefore) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryEndAtConstraint. | -| [QueryFieldFilterConstraint](./firestore_lite.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) | A QueryFieldFilterConstraint is used to narrow the set of documents returned by a Firestore query by filtering on one or more document fields. QueryFieldFilterConstraints are created by invoking [where()](./firestore_.md#where) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryFieldFilterConstraint. | -| [QueryLimitConstraint](./firestore_lite.querylimitconstraint.md#querylimitconstraint_class) | A QueryLimitConstraint is used to limit the number of documents returned by a Firestore query. QueryLimitConstraints are created by invoking [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryLimitConstraint. | -| [QueryOrderByConstraint](./firestore_lite.queryorderbyconstraint.md#queryorderbyconstraint_class) | A QueryOrderByConstraint is used to sort the set of documents returned by a Firestore query. QueryOrderByConstraints are created by invoking [orderBy()](./firestore_.md#orderby) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryOrderByConstraint.Note: Documents that do not contain the orderBy field will not be present in the query result. | -| [QuerySnapshot](./firestore_lite.querysnapshot.md#querysnapshot_class) | A QuerySnapshot contains zero or more DocumentSnapshot objects representing the results of a query. The documents can be accessed as an array via the docs property or enumerated using the forEach method. The number of documents can be determined via the empty and size properties. | -| [QueryStartAtConstraint](./firestore_lite.querystartatconstraint.md#querystartatconstraint_class) | A QueryStartAtConstraint is used to exclude documents from the start of a result set returned by a Firestore query. QueryStartAtConstraints are created by invoking [startAt()](./firestore_.md#startat) or [startAfter()](./firestore_.md#startafter) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryStartAtConstraint. | -| [Timestamp](./firestore_lite.timestamp.md#timestamp_class) | A Timestamp represents a point in time independent of any time zone or calendar, represented as seconds and fractions of seconds at nanosecond resolution in UTC Epoch time.It is encoded using the Proleptic Gregorian Calendar which extends the Gregorian calendar backwards to year one. It is encoded assuming all minutes are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.For examples and further specifications, refer to the [Timestamp definition](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto). | -| [Transaction](./firestore_lite.transaction.md#transaction_class) | A reference to a transaction.The Transaction object passed to a transaction's updateFunction provides the methods to read and write data within the transaction context. See [runTransaction()](./firestore_.md#runtransaction). | -| [WriteBatch](./firestore_lite.writebatch.md#writebatch_class) | A write batch, used to perform multiple writes as a single atomic unit.A WriteBatch object can be acquired by calling [writeBatch()](./firestore_.md#writebatch). It provides methods for adding writes to the write batch. None of the writes will be committed (or visible locally) until [WriteBatch.commit()](./firestore_.writebatch.md#writebatchcommit) is called. | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [AggregateSpec](./firestore_lite.aggregatespec.md#aggregatespec_interface) | A type whose property values are all AggregateField objects. | -| [DocumentData](./firestore_lite.documentdata.md#documentdata_interface) | Document data (for use with [setDoc()](./firestore_lite.md#setdoc)) consists of fields mapped to values. | -| [FirestoreDataConverter](./firestore_lite.firestoredataconverter.md#firestoredataconverter_interface) | Converter used by withConverter() to transform user objects of type T into Firestore data.Using the converter allows you to specify generic type arguments when storing and retrieving objects from Firestore. | -| [Settings](./firestore_lite.settings.md#settings_interface) | Specifies custom configurations for your Cloud Firestore instance. You must set these before invoking any other methods. | -| [TransactionOptions](./firestore_lite.transactionoptions.md#transactionoptions_interface) | Options to customize transaction behavior. | - -## Type Aliases - -| Type Alias | Description | -| --- | --- | -| [AddPrefixToKeys](./firestore_lite.md#addprefixtokeys) | Returns a new map where every key is prefixed with the outer key appended to a dot. | -| [AggregateFieldType](./firestore_lite.md#aggregatefieldtype) | The union of all AggregateField types that are supported by Firestore. | -| [AggregateSpecData](./firestore_lite.md#aggregatespecdata) | A type whose keys are taken from an AggregateSpec, and whose values are the result of the aggregation performed by the corresponding AggregateField from the input AggregateSpec. | -| [ChildUpdateFields](./firestore_lite.md#childupdatefields) | Helper for calculating the nested fields for a given type T1. This is needed to distribute union types such as undefined | {...} (happens for optional props) or {a: A} | {b: B}.In this use case, V is used to distribute the union types of T[K] on Record, since T[K] is evaluated as an expression and not distributed.See https://www.typescriptlang.org/docs/handbook/advanced-types.html\#distributive-conditional-types | -| [FirestoreErrorCode](./firestore_lite.md#firestoreerrorcode) | The set of Firestore status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.mdPossible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (e.g. an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation. | -| [NestedUpdateFields](./firestore_lite.md#nestedupdatefields) | For each field (e.g. 'bar'), find all nested keys (e.g. {'bar.baz': T1, 'bar.qux': T2}). Intersect them together to make a single map containing all possible keys that are all marked as optional | -| [OrderByDirection](./firestore_lite.md#orderbydirection) | The direction of a [orderBy()](./firestore_.md#orderby) clause is specified as 'desc' or 'asc' (descending or ascending). | -| [PartialWithFieldValue](./firestore_lite.md#partialwithfieldvalue) | Similar to Typescript's Partial<T>, but allows nested fields to be omitted and FieldValues to be passed in as property values. | -| [Primitive](./firestore_lite.md#primitive) | Primitive types. | -| [QueryConstraintType](./firestore_lite.md#queryconstrainttype) | Describes the different query constraints available in this SDK. | -| [QueryNonFilterConstraint](./firestore_lite.md#querynonfilterconstraint) | QueryNonFilterConstraint is a helper union type that represents QueryConstraints which are used to narrow or order the set of documents, but that do not explicitly filter on a document field. QueryNonFilterConstraints are created by invoking [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains the QueryConstraint. | -| [SetOptions](./firestore_lite.md#setoptions) | An options object that configures the behavior of [setDoc()](./firestore_lite.md#setdoc), and calls. These calls can be configured to perform granular merges instead of overwriting the target documents in their entirety by providing a SetOptions with merge: true. | -| [UnionToIntersection](./firestore_lite.md#uniontointersection) | Given a union type U = T1 | T2 | ..., returns an intersected type (T1 & T2 & ...).Uses distributive conditional types and inference from conditional types. This works because multiple candidates for the same type variable in contra-variant positions causes an intersection type to be inferred. https://www.typescriptlang.org/docs/handbook/advanced-types.html\#type-inference-in-conditional-types https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection-type | -| [UpdateData](./firestore_lite.md#updatedata) | Update data (for use with [updateDoc()](./firestore_.md#updatedoc)) that consists of field paths (e.g. 'foo' or 'foo.baz') mapped to values. Fields that contain dots reference nested fields within the document. FieldValues can be passed in as property values. | -| [WhereFilterOp](./firestore_lite.md#wherefilterop) | Filter conditions in a [where()](./firestore_.md#where) clause are specified using the strings '&lt;', '&lt;=', '==', '!=', '&gt;=', '&gt;', 'array-contains', 'in', 'array-contains-any', and 'not-in'. | -| [WithFieldValue](./firestore_lite.md#withfieldvalue) | Allows FieldValues to be passed in as a property value while maintaining type safety. | - -## 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. - -Signature: - -```typescript -export declare function getFirestore(app: FirebaseApp): Firestore; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance that the returned [Firestore](./firestore_.firestore.md#firestore_class) instance is associated with. | - -Returns: - -[Firestore](./firestore_lite.firestore.md#firestore_class) - -The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. - -## initializeFirestore() - -Initializes a new instance of Cloud Firestore with the provided settings. Can only be called before any other functions, including [getFirestore()](./firestore_.md#getfirestore). If the custom settings are empty, this function is equivalent to calling [getFirestore()](./firestore_.md#getfirestore). - -Signature: - -```typescript -export declare function initializeFirestore(app: FirebaseApp, settings: Settings): Firestore; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) with which the Firestore instance will be associated. | -| settings | [Settings](./firestore_lite.settings.md#settings_interface) | A settings object to configure the Firestore instance. | - -Returns: - -[Firestore](./firestore_lite.firestore.md#firestore_class) - -A newly initialized `Firestore` instance. - -## collection() - -Gets a `CollectionReference` instance that refers to the collection at the specified absolute path. - -Signature: - -```typescript -export declare function collection(firestore: Firestore, path: string, ...pathSegments: string[]): CollectionReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | A reference to the root Firestore instance. | -| path | string | A slash-separated path to a collection. | -| pathSegments | string\[\] | Additional path segments to apply relative to the first argument. | - -Returns: - -[CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> - -The `CollectionReference` instance. - -## Exceptions - -If the final path has an even number of segments and does not point to a collection. - -## collectionGroup() - -Creates and returns a new `Query` instance that includes all documents in the database that are contained in a collection or subcollection with the given `collectionId`. - -Signature: - -```typescript -export declare function collectionGroup(firestore: Firestore, collectionId: string): Query; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | A reference to the root Firestore instance. | -| collectionId | string | Identifies the collections to query over. Every collection or subcollection with this ID as the last segment of its path will be included. Cannot contain a slash. | - -Returns: - -[Query](./firestore_lite.query.md#query_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> - -The created `Query`. - -## connectFirestoreEmulator() - -Modify this instance to communicate with the Cloud Firestore emulator. - -Note: This must be called before this instance has been used to do any operations. - -Signature: - -```typescript -export declare function connectFirestoreEmulator(firestore: Firestore, host: string, port: number, options?: { - mockUserToken?: EmulatorMockTokenOptions | string; -}): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | The Firestore instance to configure to connect to the emulator. | -| host | string | the emulator host (ex: localhost). | -| port | number | the emulator port (ex: 9000). | -| options | { mockUserToken?: [EmulatorMockTokenOptions](./util.md#emulatormocktokenoptions) \| string; } | | - -Returns: - -void - -## doc() - -Gets a `DocumentReference` instance that refers to the document at the specified absolute path. - -Signature: - -```typescript -export declare function doc(firestore: Firestore, path: string, ...pathSegments: string[]): DocumentReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | A reference to the root Firestore instance. | -| path | string | A slash-separated path to a document. | -| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | - -Returns: - -[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> - -The `DocumentReference` instance. - -## Exceptions - -If the final path has an odd number of segments and does not point to a document. - -## runTransaction() - -Executes the given `updateFunction` and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, Cloud Firestore retries the `updateFunction`. If it fails to commit after 5 attempts, the transaction fails. - -The maximum number of writes allowed in a single transaction is 500. - -Signature: - -```typescript -export declare function runTransaction(firestore: Firestore, updateFunction: (transaction: Transaction) => Promise, options?: TransactionOptions): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | A reference to the Firestore database to run this transaction against. | -| updateFunction | (transaction: [Transaction](./firestore_lite.transaction.md#transaction_class)) => Promise<T> | The function to execute within the transaction context. | -| options | [TransactionOptions](./firestore_lite.transactionoptions.md#transactionoptions_interface) | An options object to configure maximum number of attempts to commit. | - -Returns: - -Promise<T> - -If the transaction completed successfully or was explicitly aborted (the `updateFunction` returned a failed promise), the promise returned by the `updateFunction `is returned here. Otherwise, if the transaction failed, a rejected promise with the corresponding failure error is returned. - -## terminate() - -Terminates the provided `Firestore` instance. - -After calling `terminate()` only the `clearIndexedDbPersistence()` functions may be used. Any other function will throw a `FirestoreError`. Termination does not cancel any pending writes, and any promises that are awaiting a response from the server will not be resolved. - -To restart after termination, create a new instance of `Firestore` with [getFirestore()](./firestore_.md#getfirestore). - -Note: Under normal circumstances, calling `terminate()` is not required. This function is useful only when you want to force this instance to release all of its resources or in combination with [clearIndexedDbPersistence()](./firestore_.md#clearindexeddbpersistence) to ensure that all local state is destroyed between test runs. - -Signature: - -```typescript -export declare function terminate(firestore: Firestore): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | The Firestore instance to terminate. | - -Returns: - -Promise<void> - -A `Promise` that is resolved when the instance has been successfully terminated. - -## writeBatch() - -Creates a write batch, used for performing multiple writes as a single atomic operation. The maximum number of writes allowed in a single WriteBatch is 500. - -The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. - -Signature: - -```typescript -export declare function writeBatch(firestore: Firestore): WriteBatch; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | | - -Returns: - -[WriteBatch](./firestore_lite.writebatch.md#writebatch_class) - -A `WriteBatch` that can be used to atomically execute multiple writes. - -## deleteField() - -Returns a sentinel for use with [updateDoc()](./firestore_lite.md#updatedoc) or [setDoc()](./firestore_lite.md#setdoc) with `{merge: true}` to mark a field for deletion. - -Signature: - -```typescript -export declare function deleteField(): FieldValue; -``` -Returns: - -[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) - -## documentId() - -Returns a special sentinel `FieldPath` to refer to the ID of a document. It can be used in queries to sort or filter by the document ID. - -Signature: - -```typescript -export declare function documentId(): FieldPath; -``` -Returns: - -[FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) - -## getFirestore() - -Returns the existing default [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: - -```typescript -export declare function getFirestore(): Firestore; -``` -Returns: - -[Firestore](./firestore_lite.firestore.md#firestore_class) - -The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. - -## 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. - -Signature: - -```typescript -export declare function serverTimestamp(): FieldValue; -``` -Returns: - -[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) - -## 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. - -Signature: - -```typescript -export declare function arrayRemove(...elements: unknown[]): FieldValue; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| elements | unknown\[\] | The elements to remove from the array. | - -Returns: - -[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) - -The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()` - -## 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. - -Signature: - -```typescript -export declare function arrayUnion(...elements: unknown[]): FieldValue; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| elements | unknown\[\] | The elements to union into the array. | - -Returns: - -[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) - -The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()`. - -## orderBy() - -Creates a [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class) that sorts the query result by the specified field, optionally in descending order instead of ascending. - -Note: Documents that do not contain the specified field will not be present in the query result. - -Signature: - -```typescript -export declare function orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDirection): QueryOrderByConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldPath | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The field to sort by. | -| directionStr | [OrderByDirection](./firestore_lite.md#orderbydirection) | Optional direction to sort by ('asc' or 'desc'). If not specified, order will be ascending. | - -Returns: - -[QueryOrderByConstraint](./firestore_lite.queryorderbyconstraint.md#queryorderbyconstraint_class) - -The created [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class). - -## where() - -Creates a [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) that enforces that documents must contain the specified field and that the value should satisfy the relation constraint provided. - -Signature: - -```typescript -export declare function where(fieldPath: string | FieldPath, opStr: WhereFilterOp, value: unknown): QueryFieldFilterConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldPath | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The path to compare | -| opStr | [WhereFilterOp](./firestore_lite.md#wherefilterop) | The operation string (e.g "&lt;", "&lt;=", "==", "&lt;", "&lt;=", "!="). | -| value | unknown | The value for comparison | - -Returns: - -[QueryFieldFilterConstraint](./firestore_lite.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) - -The created [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class). - -## endAt() - -Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. - -Signature: - -```typescript -export declare function endAt(...fieldValues: unknown[]): QueryEndAtConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldValues | unknown\[\] | The field values to end this query at, in order of the query's order by. | - -Returns: - -[QueryEndAtConstraint](./firestore_lite.queryendatconstraint.md#queryendatconstraint_class) - -A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` - -## endBefore() - -Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. - -Signature: - -```typescript -export declare function endBefore(...fieldValues: unknown[]): QueryEndAtConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldValues | unknown\[\] | The field values to end this query before, in order of the query's order by. | - -Returns: - -[QueryEndAtConstraint](./firestore_lite.queryendatconstraint.md#queryendatconstraint_class) - -A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` - -## startAfter() - -Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. - -Signature: - -```typescript -export declare function startAfter(...fieldValues: unknown[]): QueryStartAtConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldValues | unknown\[\] | The field values to start this query after, in order of the query's order by. | - -Returns: - -[QueryStartAtConstraint](./firestore_lite.querystartatconstraint.md#querystartatconstraint_class) - -A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()` - -## startAt() - -Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. - -Signature: - -```typescript -export declare function startAt(...fieldValues: unknown[]): QueryStartAtConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| fieldValues | unknown\[\] | The field values to start this query at, in order of the query's order by. | - -Returns: - -[QueryStartAtConstraint](./firestore_lite.querystartatconstraint.md#querystartatconstraint_class) - -A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()`. - -## aggregateQuerySnapshotEqual() - -Compares two `AggregateQuerySnapshot` instances for equality. - -Two `AggregateQuerySnapshot` instances are considered "equal" if they have underlying queries that compare equal, and the same data. - -Signature: - -```typescript -export declare function aggregateQuerySnapshotEqual(left: AggregateQuerySnapshot, right: AggregateQuerySnapshot): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| left | [AggregateQuerySnapshot](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<T> | The first AggregateQuerySnapshot to compare. | -| right | [AggregateQuerySnapshot](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<T> | The second AggregateQuerySnapshot to compare. | - -Returns: - -boolean - -`true` if the objects are "equal", as defined above, or `false` otherwise. - -## queryEqual() - -Returns true if the provided queries point to the same collection and apply the same constraints. - -Signature: - -```typescript -export declare function queryEqual(left: Query, right: Query): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| left | [Query](./firestore_lite.query.md#query_class)<T> | A Query to compare. | -| right | [Query](./firestore_lite.query.md#query_class)<T> | A Query to compare. | - -Returns: - -boolean - -true if the references point to the same location in the same Firestore database. - -## refEqual() - -Returns true if the provided references are equal. - -Signature: - -```typescript -export declare function refEqual(left: DocumentReference | CollectionReference, right: DocumentReference | CollectionReference): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| left | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> \| [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | A reference to compare. | -| right | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> \| [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | A reference to compare. | - -Returns: - -boolean - -true if the references point to the same location in the same Firestore database. - -## snapshotEqual() - -Returns true if the provided snapshots are equal. - -Signature: - -```typescript -export declare function snapshotEqual(left: DocumentSnapshot | QuerySnapshot, right: DocumentSnapshot | QuerySnapshot): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| left | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<T> \| [QuerySnapshot](./firestore_lite.querysnapshot.md#querysnapshot_class)<T> | A snapshot to compare. | -| right | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<T> \| [QuerySnapshot](./firestore_lite.querysnapshot.md#querysnapshot_class)<T> | A snapshot to compare. | - -Returns: - -boolean - -true if the snapshots are equal. - -## limit() - -Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the first matching documents. - -Signature: - -```typescript -export declare function limit(limit: number): QueryLimitConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| limit | number | The maximum number of items to return. | - -Returns: - -[QueryLimitConstraint](./firestore_lite.querylimitconstraint.md#querylimitconstraint_class) - -The created [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class). - -## limitToLast() - -Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the last matching documents. - -You must specify at least one `orderBy` clause for `limitToLast` queries, otherwise an exception will be thrown during execution. - -Signature: - -```typescript -export declare function limitToLast(limit: number): QueryLimitConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| limit | number | The maximum number of items to return. | - -Returns: - -[QueryLimitConstraint](./firestore_lite.querylimitconstraint.md#querylimitconstraint_class) - -The created [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class). - -## setLogLevel() - -Sets the verbosity of Cloud Firestore logs (debug, error, or silent). - -Signature: - -```typescript -export declare function setLogLevel(logLevel: LogLevel): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| logLevel | LogLevel | The verbosity you set for activity and error logging. Can be any of the following values:
  • debug for the most verbose logging level, primarily for debugging.
  • error to log errors only.
  • silent to turn off logging.
| - -Returns: - -void - -## increment() - -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 increment the field's current value by the given value. - -If either the operand or the current field value uses floating point precision, all arithmetic follows IEEE 754 semantics. If both values are integers, values outside of JavaScript's safe number range (`Number.MIN_SAFE_INTEGER` to `Number.MAX_SAFE_INTEGER`) are also subject to precision loss. Furthermore, once processed by the Firestore backend, all integer operations are capped between -2^63 and 2^63-1. - -If the current field value is not of type `number`, or if the field does not yet exist, the transformation sets the field to the given value. - -Signature: - -```typescript -export declare function increment(n: number): FieldValue; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| n | number | The value to increment by. | - -Returns: - -[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) - -The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()` - -## getCount() - -Calculates the number of documents in the result set of the given query, without actually downloading the documents. - -Using this function to count the documents is efficient because only the final count, not the documents' data, is downloaded. This function can even count the documents if the result set would be prohibitively large to download entirely (e.g. thousands of documents). - -Signature: - -```typescript -export declare function getCount(query: Query): Promise; -}>>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./firestore_lite.query.md#query_class)<unknown> | The query whose result set size to calculate. | - -Returns: - -Promise<[AggregateQuerySnapshot](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<{ count: [AggregateField](./firestore_lite.aggregatefield.md#aggregatefield_class)<number>; }>> - -A Promise that will be resolved with the count; the count can be retrieved from `snapshot.data().count`, where `snapshot` is the `AggregateQuerySnapshot` to which the returned Promise resolves. - -## getDocs() - -Executes the query and returns the results as a [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class). - -All queries are executed directly by the server, even if the the query was previously executed. Recent modifications are only reflected in the retrieved results if they have already been applied by the backend. If the client is offline, the operation fails. To see previously cached result and local modifications, use the full Firestore SDK. - -Signature: - -```typescript -export declare function getDocs(query: Query): Promise>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./firestore_lite.query.md#query_class)<T> | The Query to execute. | - -Returns: - -Promise<[QuerySnapshot](./firestore_lite.querysnapshot.md#querysnapshot_class)<T>> - -A Promise that will be resolved with the results of the query. - -## query() - -Creates a new immutable instance of [Query](./firestore_.query.md#query_class) that is extended to also include additional query constraints. - -Signature: - -```typescript -export declare function query(query: Query, ...queryConstraints: QueryConstraint[]): Query; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| query | [Query](./firestore_lite.query.md#query_class)<T> | The [Query](./firestore_.query.md#query_class) instance to use as a base for the new constraints. | -| queryConstraints | [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class)\[\] | The list of [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class)s to apply. | - -Returns: - -[Query](./firestore_lite.query.md#query_class)<T> - -## Exceptions - -if any of the provided query constraints cannot be combined with the existing or new constraints. - -## addDoc() - -Add a new document to specified `CollectionReference` with the given data, assigning it a document ID automatically. - -The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. - -Signature: - -```typescript -export declare function addDoc(reference: CollectionReference, data: WithFieldValue): Promise>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | A reference to the collection to add this document to. | -| data | [WithFieldValue](./firestore_lite.md#withfieldvalue)<T> | An Object containing the data for the new document. | - -Returns: - -Promise<[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T>> - -A `Promise` resolved with a `DocumentReference` pointing to the newly created document after it has been written to the backend. - -## Exceptions - -Error - If the provided input is not a valid Firestore document. - -## collection() - -Gets a `CollectionReference` instance that refers to a subcollection of `reference` at the the specified relative path. - -Signature: - -```typescript -export declare function collection(reference: CollectionReference, path: string, ...pathSegments: string[]): CollectionReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<unknown> | A reference to a collection. | -| path | string | A slash-separated path to a collection. | -| pathSegments | string\[\] | Additional path segments to apply relative to the first argument. | - -Returns: - -[CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> - -The `CollectionReference` instance. - -## Exceptions - -If the final path has an even number of segments and does not point to a collection. - -## collection() - -Gets a `CollectionReference` instance that refers to a subcollection of `reference` at the the specified relative path. - -Signature: - -```typescript -export declare function collection(reference: DocumentReference, path: string, ...pathSegments: string[]): CollectionReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class) | A reference to a Firestore document. | -| path | string | A slash-separated path to a collection. | -| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | - -Returns: - -[CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> - -The `CollectionReference` instance. - -## Exceptions - -If the final path has an even number of segments and does not point to a collection. - -## deleteDoc() - -Deletes the document referred to by the specified `DocumentReference`. - -The deletion will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the delete fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. - -Signature: - -```typescript -export declare function deleteDoc(reference: DocumentReference): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to the document to delete. | - -Returns: - -Promise<void> - -A `Promise` resolved once the document has been successfully deleted from the backend. - -## doc() - -Gets a `DocumentReference` instance that refers to a document within `reference` at the specified relative path. If no path is specified, an automatically-generated unique ID will be used for the returned `DocumentReference`. - -Signature: - -```typescript -export declare function doc(reference: CollectionReference, path?: string, ...pathSegments: string[]): DocumentReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | A reference to a collection. | -| path | string | A slash-separated path to a document. Has to be omitted to use auto-genrated IDs. | -| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | - -Returns: - -[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> - -The `DocumentReference` instance. - -## Exceptions - -If the final path has an odd number of segments and does not point to a document. - -## doc() - -Gets a `DocumentReference` instance that refers to a document within `reference` at the specified relative path. - -Signature: - -```typescript -export declare function doc(reference: DocumentReference, path: string, ...pathSegments: string[]): DocumentReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to a Firestore document. | -| path | string | A slash-separated path to a document. | -| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | - -Returns: - -[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> - -The `DocumentReference` instance. - -## Exceptions - -If the final path has an odd number of segments and does not point to a document. - -## getDoc() - -Reads the document referred to by the specified document reference. - -All documents are directly fetched from the server, even if the document was previously read or modified. Recent modifications are only reflected in the retrieved `DocumentSnapshot` if they have already been applied by the backend. If the client is offline, the read fails. If you like to use caching or see local modifications, please use the full Firestore SDK. - -Signature: - -```typescript -export declare function getDoc(reference: DocumentReference): Promise>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | The reference of the document to fetch. | - -Returns: - -Promise<[DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<T>> - -A Promise resolved with a `DocumentSnapshot` containing the current document contents. - -## setDoc() - -Writes to the document referred to by the specified `DocumentReference`. If the document does not yet exist, it will be created. - -The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. - -Signature: - -```typescript -export declare function setDoc(reference: DocumentReference, data: WithFieldValue): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to write. | -| data | [WithFieldValue](./firestore_lite.md#withfieldvalue)<T> | A map of the fields and values for the document. | - -Returns: - -Promise<void> - -A `Promise` resolved once the data has been successfully written to the backend. - -## Exceptions - -Error - If the provided input is not a valid Firestore document. - -## setDoc() - -Writes to the document referred to by the specified `DocumentReference`. If the document does not yet exist, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. - -The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. - -Signature: - -```typescript -export declare function setDoc(reference: DocumentReference, data: PartialWithFieldValue, options: SetOptions): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to write. | -| data | [PartialWithFieldValue](./firestore_lite.md#partialwithfieldvalue)<T> | A map of the fields and values for the document. | -| options | [SetOptions](./firestore_lite.md#setoptions) | An object to configure the set behavior. | - -Returns: - -Promise<void> - -A `Promise` resolved once the data has been successfully written to the backend. - -## Exceptions - -Error - If the provided input is not a valid Firestore document. - -## updateDoc() - -Updates fields in the document referred to by the specified `DocumentReference`. The update will fail if applied to a document that does not exist. - -The result of this update will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the update fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. - -Signature: - -```typescript -export declare function updateDoc(reference: DocumentReference, data: UpdateData): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to update. | -| data | [UpdateData](./firestore_lite.md#updatedata)<T> | An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document. | - -Returns: - -Promise<void> - -A `Promise` resolved once the data has been successfully written to the backend. - -## Exceptions - -Error - If the provided input is not valid Firestore data. - -## updateDoc() - -Updates fields in the document referred to by the specified `DocumentReference` The update will fail if applied to a document that does not exist. - -Nested fields can be updated by providing dot-separated field path strings or by providing `FieldPath` objects. - -The result of this update will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the update fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. - -Signature: - -```typescript -export declare function updateDoc(reference: DocumentReference, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to the document to update. | -| field | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The first field to update. | -| value | unknown | The first value. | -| moreFieldsAndValues | unknown\[\] | Additional key value pairs. | - -Returns: - -Promise<void> - -A `Promise` resolved once the data has been successfully written to the backend. - -## Exceptions - -Error - If the provided input is not valid Firestore data. - -## endAt() - -Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided document (inclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. - -Signature: - -```typescript -export declare function endAt(snapshot: DocumentSnapshot): QueryEndAtConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| snapshot | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to end at. | - -Returns: - -[QueryEndAtConstraint](./firestore_lite.queryendatconstraint.md#queryendatconstraint_class) - -A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` - -## endBefore() - -Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. - -Signature: - -```typescript -export declare function endBefore(snapshot: DocumentSnapshot): QueryEndAtConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| snapshot | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to end before. | - -Returns: - -[QueryEndAtConstraint](./firestore_lite.queryendatconstraint.md#queryendatconstraint_class) - -A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` - -## startAfter() - -Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. - -Signature: - -```typescript -export declare function startAfter(snapshot: DocumentSnapshot): QueryStartAtConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| snapshot | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to start after. | - -Returns: - -[QueryStartAtConstraint](./firestore_lite.querystartatconstraint.md#querystartatconstraint_class) - -A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()` - -## startAt() - -Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the `orderBy` of this query. - -Signature: - -```typescript -export declare function startAt(snapshot: DocumentSnapshot): QueryStartAtConstraint; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| snapshot | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to start at. | - -Returns: - -[QueryStartAtConstraint](./firestore_lite.querystartatconstraint.md#querystartatconstraint_class) - -A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()`. - -## AddPrefixToKeys - -Returns a new map where every key is prefixed with the outer key appended to a dot. - -Signature: - -```typescript -export declare type AddPrefixToKeys> = { - [K in keyof T & string as `${Prefix}.${K}`]+?: T[K]; -}; -``` - -## AggregateFieldType - -The union of all `AggregateField` types that are supported by Firestore. - -Signature: - -```typescript -export declare type AggregateFieldType = AggregateField; -``` - -## AggregateSpecData - -A type whose keys are taken from an `AggregateSpec`, and whose values are the result of the aggregation performed by the corresponding `AggregateField` from the input `AggregateSpec`. - -Signature: - -```typescript -export declare type AggregateSpecData = { - [P in keyof T]: T[P] extends AggregateField ? U : never; -}; -``` - -## ChildUpdateFields - -Helper for calculating the nested fields for a given type T1. This is needed to distribute union types such as `undefined | {...}` (happens for optional props) or `{a: A} | {b: B}`. - -In this use case, `V` is used to distribute the union types of `T[K]` on `Record`, since `T[K]` is evaluated as an expression and not distributed. - -See https://www.typescriptlang.org/docs/handbook/advanced-types.html\#distributive-conditional-types - -Signature: - -```typescript -export declare type ChildUpdateFields = V extends Record ? AddPrefixToKeys> : never; -``` - -## FirestoreErrorCode - -The set of Firestore status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.md - -Possible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (e.g. an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation. - -Signature: - -```typescript -export declare type FirestoreErrorCode = 'cancelled' | 'unknown' | 'invalid-argument' | 'deadline-exceeded' | 'not-found' | 'already-exists' | 'permission-denied' | 'resource-exhausted' | 'failed-precondition' | 'aborted' | 'out-of-range' | 'unimplemented' | 'internal' | 'unavailable' | 'data-loss' | 'unauthenticated'; -``` - -## NestedUpdateFields - -For each field (e.g. 'bar'), find all nested keys (e.g. {'bar.baz': T1, 'bar.qux': T2}). Intersect them together to make a single map containing all possible keys that are all marked as optional - -Signature: - -```typescript -export declare type NestedUpdateFields> = UnionToIntersection<{ - [K in keyof T & string]: ChildUpdateFields; -}[keyof T & string]>; -``` - -## OrderByDirection - -The direction of a [orderBy()](./firestore_.md#orderby) clause is specified as 'desc' or 'asc' (descending or ascending). - -Signature: - -```typescript -export declare type OrderByDirection = 'desc' | 'asc'; -``` - -## PartialWithFieldValue - -Similar to Typescript's `Partial`, but allows nested fields to be omitted and FieldValues to be passed in as property values. - -Signature: - -```typescript -export declare type PartialWithFieldValue = Partial | (T extends Primitive ? T : T extends {} ? { - [K in keyof T]?: PartialWithFieldValue | FieldValue; -} : never); -``` - -## Primitive - -Primitive types. - -Signature: - -```typescript -export declare type Primitive = string | number | boolean | undefined | null; -``` - -## QueryConstraintType - -Describes the different query constraints available in this SDK. - -Signature: - -```typescript -export declare type QueryConstraintType = 'where' | 'orderBy' | 'limit' | 'limitToLast' | 'startAt' | 'startAfter' | 'endAt' | 'endBefore'; -``` - -## QueryNonFilterConstraint - -`QueryNonFilterConstraint` is a helper union type that represents QueryConstraints which are used to narrow or order the set of documents, but that do not explicitly filter on a document field. `QueryNonFilterConstraint`s are created by invoking [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains the `QueryConstraint`. - -Signature: - -```typescript -export declare type QueryNonFilterConstraint = QueryOrderByConstraint | QueryLimitConstraint | QueryStartAtConstraint | QueryEndAtConstraint; -``` - -## SetOptions - -An options object that configures the behavior of [setDoc()](./firestore_lite.md#setdoc), and calls. These calls can be configured to perform granular merges instead of overwriting the target documents in their entirety by providing a `SetOptions` with `merge: true`. - -Signature: - -```typescript -export declare type SetOptions = { - readonly merge?: boolean; -} | { - readonly mergeFields?: Array; -}; -``` - -## UnionToIntersection - -Given a union type `U = T1 | T2 | ...`, returns an intersected type `(T1 & T2 & ...)`. - -Uses distributive conditional types and inference from conditional types. This works because multiple candidates for the same type variable in contra-variant positions causes an intersection type to be inferred. https://www.typescriptlang.org/docs/handbook/advanced-types.html\#type-inference-in-conditional-types https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection-type - -Signature: - -```typescript -export declare type UnionToIntersection = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never; -``` - -## UpdateData - -Update data (for use with [updateDoc()](./firestore_.md#updatedoc)) that consists of field paths (e.g. 'foo' or 'foo.baz') mapped to values. Fields that contain dots reference nested fields within the document. FieldValues can be passed in as property values. - -Signature: - -```typescript -export declare type UpdateData = T extends Primitive ? T : T extends {} ? { - [K in keyof T]?: UpdateData | FieldValue; -} & NestedUpdateFields : Partial; -``` - -## WhereFilterOp - -Filter conditions in a [where()](./firestore_.md#where) clause are specified using the strings '&lt;', '&lt;=', '==', '!=', '&gt;=', '&gt;', 'array-contains', 'in', 'array-contains-any', and 'not-in'. - -Signature: - -```typescript -export declare type WhereFilterOp = '<' | '<=' | '==' | '!=' | '>=' | '>' | 'array-contains' | 'in' | 'array-contains-any' | 'not-in'; -``` - -## WithFieldValue - -Allows FieldValues to be passed in as a property value while maintaining type safety. - -Signature: - -```typescript -export declare type WithFieldValue = T | (T extends Primitive ? T : T extends {} ? { - [K in keyof T]: WithFieldValue | FieldValue; -} : never); -``` diff --git a/docs-devsite/firestore_lite.query.md b/docs-devsite/firestore_lite.query.md deleted file mode 100644 index f2eac7560dc..00000000000 --- a/docs-devsite/firestore_lite.query.md +++ /dev/null @@ -1,125 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Query class -A `Query` refers to a query which you can read or listen to. You can also construct refined `Query` objects by adding filters and ordering. - -Signature: - -```typescript -export declare class Query -``` - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)()](./firestore_lite.query.md#queryconstructor) | | Constructs a new instance of the Query class | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [converter](./firestore_lite.query.md#queryconverter) | | [FirestoreDataConverter](./firestore_lite.firestoredataconverter.md#firestoredataconverter_interface)<T> \| null | If provided, the FirestoreDataConverter associated with this instance. | -| [firestore](./firestore_lite.query.md#queryfirestore) | | [Firestore](./firestore_lite.firestore.md#firestore_class) | The Firestore instance for the Firestore database (useful for performing transactions, etc.). | -| [type](./firestore_lite.query.md#querytype) | | 'query' \| 'collection' | The type of this Firestore reference. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [withConverter(converter)](./firestore_lite.query.md#querywithconverter) | | Removes the current converter. | -| [withConverter(converter)](./firestore_lite.query.md#querywithconverter) | | Applies a custom data converter to this query, allowing you to use your own custom model objects with Firestore. When you call [getDocs()](./firestore_.md#getdocs) with the returned query, the provided converter will convert between Firestore data and your custom type U. | - -## Query.(constructor) - -Constructs a new instance of the `Query` class - -Signature: - -```typescript -protected constructor(); -``` - -## Query.converter - -If provided, the `FirestoreDataConverter` associated with this instance. - -Signature: - -```typescript -readonly converter: FirestoreDataConverter | null; -``` - -## Query.firestore - -The `Firestore` instance for the Firestore database (useful for performing transactions, etc.). - -Signature: - -```typescript -readonly firestore: Firestore; -``` - -## Query.type - -The type of this Firestore reference. - -Signature: - -```typescript -readonly type: 'query' | 'collection'; -``` - -## Query.withConverter() - -Removes the current converter. - -Signature: - -```typescript -withConverter(converter: null): Query; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| converter | null | null removes the current converter. | - -Returns: - -[Query](./firestore_lite.query.md#query_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> - -A `Query` that does not use a converter. - -## Query.withConverter() - -Applies a custom data converter to this query, allowing you to use your own custom model objects with Firestore. When you call [getDocs()](./firestore_.md#getdocs) with the returned query, the provided converter will convert between Firestore data and your custom type `U`. - -Signature: - -```typescript -withConverter(converter: FirestoreDataConverter): Query; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| converter | [FirestoreDataConverter](./firestore_lite.firestoredataconverter.md#firestoredataconverter_interface)<U> | Converts objects to and from Firestore. | - -Returns: - -[Query](./firestore_lite.query.md#query_class)<U> - -A `Query` that uses the provided converter. - diff --git a/docs-devsite/firestore_lite.queryconstraint.md b/docs-devsite/firestore_lite.queryconstraint.md deleted file mode 100644 index dae8d5f0069..00000000000 --- a/docs-devsite/firestore_lite.queryconstraint.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryConstraint class -A `QueryConstraint` is used to narrow the set of documents returned by a Firestore query. `QueryConstraint`s are created by invoking [where()](./firestore_.md#where), [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit), [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryConstraint`. - -Signature: - -```typescript -export declare abstract class QueryConstraint -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_lite.queryconstraint.md#queryconstrainttype) | | [QueryConstraintType](./firestore_lite.md#queryconstrainttype) | The type of this query constraint | - -## QueryConstraint.type - -The type of this query constraint - -Signature: - -```typescript -abstract readonly type: QueryConstraintType; -``` diff --git a/docs-devsite/firestore_lite.querydocumentsnapshot.md b/docs-devsite/firestore_lite.querydocumentsnapshot.md deleted file mode 100644 index 356d7ecaeed..00000000000 --- a/docs-devsite/firestore_lite.querydocumentsnapshot.md +++ /dev/null @@ -1,45 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryDocumentSnapshot class -A `QueryDocumentSnapshot` contains data read from a document in your Firestore database as part of a query. The document is guaranteed to exist and its data can be extracted with `.data()` or `.get()` to get a specific field. - -A `QueryDocumentSnapshot` offers the same API surface as a `DocumentSnapshot`. Since query results contain only existing documents, the `exists` property will always be true and `data()` will never return 'undefined'. - -Signature: - -```typescript -export declare class QueryDocumentSnapshot extends DocumentSnapshot -``` -Extends: [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<T> - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [data()](./firestore_lite.querydocumentsnapshot.md#querydocumentsnapshotdata) | | Retrieves all fields in the document as an Object. | - -## QueryDocumentSnapshot.data() - -Retrieves all fields in the document as an `Object`. - -Signature: - -```typescript -/** @override */ -data(): T; -``` -Returns: - -T - -An `Object` containing all fields in the document. - diff --git a/docs-devsite/firestore_lite.queryendatconstraint.md b/docs-devsite/firestore_lite.queryendatconstraint.md deleted file mode 100644 index 7f999a414b6..00000000000 --- a/docs-devsite/firestore_lite.queryendatconstraint.md +++ /dev/null @@ -1,36 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryEndAtConstraint class -A `QueryEndAtConstraint` is used to exclude documents from the end of a result set returned by a Firestore query. `QueryEndAtConstraint`s are created by invoking [endAt()](./firestore_.md#endat) or [endBefore()](./firestore_.md#endbefore) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryEndAtConstraint`. - -Signature: - -```typescript -export declare class QueryEndAtConstraint extends QueryConstraint -``` -Extends: [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_lite.queryendatconstraint.md#queryendatconstrainttype) | | 'endBefore' \| 'endAt' | The type of this query constraint | - -## QueryEndAtConstraint.type - -The type of this query constraint - -Signature: - -```typescript -readonly type: 'endBefore' | 'endAt'; -``` diff --git a/docs-devsite/firestore_lite.queryfieldfilterconstraint.md b/docs-devsite/firestore_lite.queryfieldfilterconstraint.md deleted file mode 100644 index 81c1509223d..00000000000 --- a/docs-devsite/firestore_lite.queryfieldfilterconstraint.md +++ /dev/null @@ -1,36 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryFieldFilterConstraint class -A `QueryFieldFilterConstraint` is used to narrow the set of documents returned by a Firestore query by filtering on one or more document fields. `QueryFieldFilterConstraint`s are created by invoking [where()](./firestore_.md#where) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryFieldFilterConstraint`. - -Signature: - -```typescript -export declare class QueryFieldFilterConstraint extends QueryConstraint -``` -Extends: [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_lite.queryfieldfilterconstraint.md#queryfieldfilterconstrainttype) | | (not declared) | The type of this query constraint | - -## QueryFieldFilterConstraint.type - -The type of this query constraint - -Signature: - -```typescript -readonly type = "where"; -``` diff --git a/docs-devsite/firestore_lite.querylimitconstraint.md b/docs-devsite/firestore_lite.querylimitconstraint.md deleted file mode 100644 index 82218279e34..00000000000 --- a/docs-devsite/firestore_lite.querylimitconstraint.md +++ /dev/null @@ -1,36 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryLimitConstraint class -A `QueryLimitConstraint` is used to limit the number of documents returned by a Firestore query. `QueryLimitConstraint`s are created by invoking [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryLimitConstraint`. - -Signature: - -```typescript -export declare class QueryLimitConstraint extends QueryConstraint -``` -Extends: [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_lite.querylimitconstraint.md#querylimitconstrainttype) | | 'limit' \| 'limitToLast' | The type of this query constraint | - -## QueryLimitConstraint.type - -The type of this query constraint - -Signature: - -```typescript -readonly type: 'limit' | 'limitToLast'; -``` diff --git a/docs-devsite/firestore_lite.queryorderbyconstraint.md b/docs-devsite/firestore_lite.queryorderbyconstraint.md deleted file mode 100644 index b5a28ed3e9a..00000000000 --- a/docs-devsite/firestore_lite.queryorderbyconstraint.md +++ /dev/null @@ -1,38 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryOrderByConstraint class -A `QueryOrderByConstraint` is used to sort the set of documents returned by a Firestore query. `QueryOrderByConstraint`s are created by invoking [orderBy()](./firestore_.md#orderby) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryOrderByConstraint`. - -Note: Documents that do not contain the orderBy field will not be present in the query result. - -Signature: - -```typescript -export declare class QueryOrderByConstraint extends QueryConstraint -``` -Extends: [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_lite.queryorderbyconstraint.md#queryorderbyconstrainttype) | | (not declared) | The type of this query constraint | - -## QueryOrderByConstraint.type - -The type of this query constraint - -Signature: - -```typescript -readonly type = "orderBy"; -``` diff --git a/docs-devsite/firestore_lite.querysnapshot.md b/docs-devsite/firestore_lite.querysnapshot.md deleted file mode 100644 index 8e805af948d..00000000000 --- a/docs-devsite/firestore_lite.querysnapshot.md +++ /dev/null @@ -1,96 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QuerySnapshot class -A `QuerySnapshot` contains zero or more `DocumentSnapshot` objects representing the results of a query. The documents can be accessed as an array via the `docs` property or enumerated using the `forEach` method. The number of documents can be determined via the `empty` and `size` properties. - -Signature: - -```typescript -export declare class QuerySnapshot -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [docs](./firestore_lite.querysnapshot.md#querysnapshotdocs) | | Array<[QueryDocumentSnapshot](./firestore_lite.querydocumentsnapshot.md#querydocumentsnapshot_class)<T>> | An array of all the documents in the QuerySnapshot. | -| [empty](./firestore_lite.querysnapshot.md#querysnapshotempty) | | boolean | True if there are no documents in the QuerySnapshot. | -| [query](./firestore_lite.querysnapshot.md#querysnapshotquery) | | [Query](./firestore_lite.query.md#query_class)<T> | The query on which you called [getDocs()](./firestore_.md#getdocs) in order to get this QuerySnapshot. | -| [size](./firestore_lite.querysnapshot.md#querysnapshotsize) | | number | The number of documents in the QuerySnapshot. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [forEach(callback, thisArg)](./firestore_lite.querysnapshot.md#querysnapshotforeach) | | Enumerates all of the documents in the QuerySnapshot. | - -## QuerySnapshot.docs - -An array of all the documents in the `QuerySnapshot`. - -Signature: - -```typescript -get docs(): Array>; -``` - -## QuerySnapshot.empty - -True if there are no documents in the `QuerySnapshot`. - -Signature: - -```typescript -get empty(): boolean; -``` - -## QuerySnapshot.query - -The query on which you called [getDocs()](./firestore_.md#getdocs) in order to get this `QuerySnapshot`. - -Signature: - -```typescript -readonly query: Query; -``` - -## QuerySnapshot.size - -The number of documents in the `QuerySnapshot`. - -Signature: - -```typescript -get size(): number; -``` - -## QuerySnapshot.forEach() - -Enumerates all of the documents in the `QuerySnapshot`. - -Signature: - -```typescript -forEach(callback: (result: QueryDocumentSnapshot) => void, thisArg?: unknown): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| callback | (result: [QueryDocumentSnapshot](./firestore_lite.querydocumentsnapshot.md#querydocumentsnapshot_class)<T>) => void | A callback to be called with a QueryDocumentSnapshot for each document in the snapshot. | -| thisArg | unknown | The this binding for the callback. | - -Returns: - -void - diff --git a/docs-devsite/firestore_lite.querystartatconstraint.md b/docs-devsite/firestore_lite.querystartatconstraint.md deleted file mode 100644 index 08d6ba15103..00000000000 --- a/docs-devsite/firestore_lite.querystartatconstraint.md +++ /dev/null @@ -1,36 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# QueryStartAtConstraint class -A `QueryStartAtConstraint` is used to exclude documents from the start of a result set returned by a Firestore query. `QueryStartAtConstraint`s are created by invoking [startAt()](./firestore_.md#startat) or [startAfter()](./firestore_.md#startafter) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryStartAtConstraint`. - -Signature: - -```typescript -export declare class QueryStartAtConstraint extends QueryConstraint -``` -Extends: [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [type](./firestore_lite.querystartatconstraint.md#querystartatconstrainttype) | | 'startAt' \| 'startAfter' | The type of this query constraint | - -## QueryStartAtConstraint.type - -The type of this query constraint - -Signature: - -```typescript -readonly type: 'startAt' | 'startAfter'; -``` diff --git a/docs-devsite/firestore_lite.settings.md b/docs-devsite/firestore_lite.settings.md deleted file mode 100644 index ae792a0fc6d..00000000000 --- a/docs-devsite/firestore_lite.settings.md +++ /dev/null @@ -1,57 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Settings interface -Specifies custom configurations for your Cloud Firestore instance. You must set these before invoking any other methods. - -Signature: - -```typescript -export declare interface Settings -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [host](./firestore_lite.settings.md#settingshost) | string | The hostname to connect to. | -| [ignoreUndefinedProperties](./firestore_lite.settings.md#settingsignoreundefinedproperties) | boolean | Whether to skip nested properties that are set to undefined during object serialization. If set to true, these properties are skipped and not written to Firestore. If set to false or omitted, the SDK throws an exception when it encounters properties of type undefined. | -| [ssl](./firestore_lite.settings.md#settingsssl) | boolean | Whether to use SSL when connecting. | - -## Settings.host - -The hostname to connect to. - -Signature: - -```typescript -host?: string; -``` - -## Settings.ignoreUndefinedProperties - -Whether to skip nested properties that are set to `undefined` during object serialization. If set to `true`, these properties are skipped and not written to Firestore. If set to `false` or omitted, the SDK throws an exception when it encounters properties of type `undefined`. - -Signature: - -```typescript -ignoreUndefinedProperties?: boolean; -``` - -## Settings.ssl - -Whether to use SSL when connecting. - -Signature: - -```typescript -ssl?: boolean; -``` diff --git a/docs-devsite/firestore_lite.timestamp.md b/docs-devsite/firestore_lite.timestamp.md deleted file mode 100644 index 7b18abc69db..00000000000 --- a/docs-devsite/firestore_lite.timestamp.md +++ /dev/null @@ -1,243 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Timestamp class -A `Timestamp` represents a point in time independent of any time zone or calendar, represented as seconds and fractions of seconds at nanosecond resolution in UTC Epoch time. - -It is encoded using the Proleptic Gregorian Calendar which extends the Gregorian calendar backwards to year one. It is encoded assuming all minutes are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. - -For examples and further specifications, refer to the [Timestamp definition](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto). - -Signature: - -```typescript -export declare class Timestamp -``` - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(seconds, nanoseconds)](./firestore_lite.timestamp.md#timestampconstructor) | | Creates a new timestamp. | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [nanoseconds](./firestore_lite.timestamp.md#timestampnanoseconds) | | number | The fractions of a second at nanosecond resolution.\* | -| [seconds](./firestore_lite.timestamp.md#timestampseconds) | | number | The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [fromDate(date)](./firestore_lite.timestamp.md#timestampfromdate) | static | Creates a new timestamp from the given date. | -| [fromMillis(milliseconds)](./firestore_lite.timestamp.md#timestampfrommillis) | static | Creates a new timestamp from the given number of milliseconds. | -| [isEqual(other)](./firestore_lite.timestamp.md#timestampisequal) | | Returns true if this Timestamp is equal to the provided one. | -| [now()](./firestore_lite.timestamp.md#timestampnow) | static | Creates a new timestamp with the current date, with millisecond precision. | -| [toDate()](./firestore_lite.timestamp.md#timestamptodate) | | Converts a Timestamp to a JavaScript Date object. This conversion causes a loss of precision since Date objects only support millisecond precision. | -| [toJSON()](./firestore_lite.timestamp.md#timestamptojson) | | Returns a JSON-serializable representation of this Timestamp. | -| [toMillis()](./firestore_lite.timestamp.md#timestamptomillis) | | Converts a Timestamp to a numeric timestamp (in milliseconds since epoch). This operation causes a loss of precision. | -| [toString()](./firestore_lite.timestamp.md#timestamptostring) | | Returns a textual representation of this Timestamp. | -| [valueOf()](./firestore_lite.timestamp.md#timestampvalueof) | | Converts this object to a primitive string, which allows Timestamp objects to be compared using the >, <=, >= and > operators. | - -## Timestamp.(constructor) - -Creates a new timestamp. - -Signature: - -```typescript -constructor( - seconds: number, - nanoseconds: number); -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| seconds | number | The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive. | -| nanoseconds | number | The non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanoseconds values that count forward in time. Must be from 0 to 999,999,999 inclusive. | - -## Timestamp.nanoseconds - -The fractions of a second at nanosecond resolution.\* - -Signature: - -```typescript -readonly nanoseconds: number; -``` - -## Timestamp.seconds - -The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. - -Signature: - -```typescript -readonly seconds: number; -``` - -## Timestamp.fromDate() - -Creates a new timestamp from the given date. - -Signature: - -```typescript -static fromDate(date: Date): Timestamp; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| date | Date | The date to initialize the Timestamp from. | - -Returns: - -[Timestamp](./firestore_lite.timestamp.md#timestamp_class) - -A new `Timestamp` representing the same point in time as the given date. - -## Timestamp.fromMillis() - -Creates a new timestamp from the given number of milliseconds. - -Signature: - -```typescript -static fromMillis(milliseconds: number): Timestamp; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| milliseconds | number | Number of milliseconds since Unix epoch 1970-01-01T00:00:00Z. | - -Returns: - -[Timestamp](./firestore_lite.timestamp.md#timestamp_class) - -A new `Timestamp` representing the same point in time as the given number of milliseconds. - -## Timestamp.isEqual() - -Returns true if this `Timestamp` is equal to the provided one. - -Signature: - -```typescript -isEqual(other: Timestamp): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| other | [Timestamp](./firestore_lite.timestamp.md#timestamp_class) | The Timestamp to compare against. | - -Returns: - -boolean - -true if this `Timestamp` is equal to the provided one. - -## Timestamp.now() - -Creates a new timestamp with the current date, with millisecond precision. - -Signature: - -```typescript -static now(): Timestamp; -``` -Returns: - -[Timestamp](./firestore_lite.timestamp.md#timestamp_class) - -a new timestamp representing the current date. - -## Timestamp.toDate() - -Converts a `Timestamp` to a JavaScript `Date` object. This conversion causes a loss of precision since `Date` objects only support millisecond precision. - -Signature: - -```typescript -toDate(): Date; -``` -Returns: - -Date - -JavaScript `Date` object representing the same point in time as this `Timestamp`, with millisecond precision. - -## Timestamp.toJSON() - -Returns a JSON-serializable representation of this `Timestamp`. - -Signature: - -```typescript -toJSON(): { - seconds: number; - nanoseconds: number; - }; -``` -Returns: - -{ seconds: number; nanoseconds: number; } - -## Timestamp.toMillis() - -Converts a `Timestamp` to a numeric timestamp (in milliseconds since epoch). This operation causes a loss of precision. - -Signature: - -```typescript -toMillis(): number; -``` -Returns: - -number - -The point in time corresponding to this timestamp, represented as the number of milliseconds since Unix epoch 1970-01-01T00:00:00Z. - -## Timestamp.toString() - -Returns a textual representation of this `Timestamp`. - -Signature: - -```typescript -toString(): string; -``` -Returns: - -string - -## Timestamp.valueOf() - -Converts this object to a primitive string, which allows `Timestamp` objects to be compared using the `>`, `<=`, `>=` and `>` operators. - -Signature: - -```typescript -valueOf(): string; -``` -Returns: - -string - diff --git a/docs-devsite/firestore_lite.transaction.md b/docs-devsite/firestore_lite.transaction.md deleted file mode 100644 index c643f08d66e..00000000000 --- a/docs-devsite/firestore_lite.transaction.md +++ /dev/null @@ -1,190 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Transaction class -A reference to a transaction. - -The `Transaction` object passed to a transaction's `updateFunction` provides the methods to read and write data within the transaction context. See [runTransaction()](./firestore_.md#runtransaction). - -Signature: - -```typescript -export declare class Transaction -``` - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [delete(documentRef)](./firestore_lite.transaction.md#transactiondelete) | | Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). | -| [get(documentRef)](./firestore_lite.transaction.md#transactionget) | | Reads the document referenced by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). | -| [set(documentRef, data)](./firestore_lite.transaction.md#transactionset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. | -| [set(documentRef, data, options)](./firestore_lite.transaction.md#transactionset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document. | -| [update(documentRef, data)](./firestore_lite.transaction.md#transactionupdate) | | Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. | -| [update(documentRef, field, value, moreFieldsAndValues)](./firestore_lite.transaction.md#transactionupdate) | | Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist.Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects. | - -## Transaction.delete() - -Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). - -Signature: - -```typescript -delete(documentRef: DocumentReference): this; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to the document to be deleted. | - -Returns: - -this - -This `Transaction` instance. Used for chaining method calls. - -## Transaction.get() - -Reads the document referenced by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). - -Signature: - -```typescript -get(documentRef: DocumentReference): Promise>; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be read. | - -Returns: - -Promise<[DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<T>> - -A `DocumentSnapshot` with the read data. - -## Transaction.set() - -Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. - -Signature: - -```typescript -set(documentRef: DocumentReference, data: WithFieldValue): this; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | -| data | [WithFieldValue](./firestore_lite.md#withfieldvalue)<T> | An object of the fields and values for the document. | - -Returns: - -this - -This `Transaction` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not a valid Firestore document. - -## Transaction.set() - -Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. - -Signature: - -```typescript -set(documentRef: DocumentReference, data: PartialWithFieldValue, options: SetOptions): this; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | -| data | [PartialWithFieldValue](./firestore_lite.md#partialwithfieldvalue)<T> | An object of the fields and values for the document. | -| options | [SetOptions](./firestore_lite.md#setoptions) | An object to configure the set behavior. | - -Returns: - -this - -This `Transaction` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not a valid Firestore document. - -## Transaction.update() - -Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. - -Signature: - -```typescript -update(documentRef: DocumentReference, data: UpdateData): this; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be updated. | -| data | [UpdateData](./firestore_lite.md#updatedata)<T> | An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document. | - -Returns: - -this - -This `Transaction` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not valid Firestore data. - -## Transaction.update() - -Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. - -Nested fields can be updated by providing dot-separated field path strings or by providing `FieldPath` objects. - -Signature: - -```typescript -update(documentRef: DocumentReference, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): this; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to the document to be updated. | -| field | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The first field to update. | -| value | unknown | The first value. | -| moreFieldsAndValues | unknown\[\] | Additional key/value pairs. | - -Returns: - -this - -This `Transaction` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not valid Firestore data. - diff --git a/docs-devsite/firestore_lite.transactionoptions.md b/docs-devsite/firestore_lite.transactionoptions.md deleted file mode 100644 index 94941df172a..00000000000 --- a/docs-devsite/firestore_lite.transactionoptions.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# TransactionOptions interface -Options to customize transaction behavior. - -Signature: - -```typescript -export declare interface TransactionOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [maxAttempts](./firestore_lite.transactionoptions.md#transactionoptionsmaxattempts) | number | Maximum number of attempts to commit, after which transaction fails. Default is 5. | - -## TransactionOptions.maxAttempts - -Maximum number of attempts to commit, after which transaction fails. Default is 5. - -Signature: - -```typescript -readonly maxAttempts?: number; -``` diff --git a/docs-devsite/firestore_lite.writebatch.md b/docs-devsite/firestore_lite.writebatch.md deleted file mode 100644 index 141a99e8585..00000000000 --- a/docs-devsite/firestore_lite.writebatch.md +++ /dev/null @@ -1,181 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# WriteBatch class -A write batch, used to perform multiple writes as a single atomic unit. - -A `WriteBatch` object can be acquired by calling [writeBatch()](./firestore_.md#writebatch). It provides methods for adding writes to the write batch. None of the writes will be committed (or visible locally) until [WriteBatch.commit()](./firestore_.writebatch.md#writebatchcommit) is called. - -Signature: - -```typescript -export declare class WriteBatch -``` - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [commit()](./firestore_lite.writebatch.md#writebatchcommit) | | Commits all of the writes in this write batch as a single atomic unit.The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | -| [delete(documentRef)](./firestore_lite.writebatch.md#writebatchdelete) | | Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). | -| [set(documentRef, data)](./firestore_lite.writebatch.md#writebatchset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. | -| [set(documentRef, data, options)](./firestore_lite.writebatch.md#writebatchset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document. | -| [update(documentRef, data)](./firestore_lite.writebatch.md#writebatchupdate) | | Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. | -| [update(documentRef, field, value, moreFieldsAndValues)](./firestore_lite.writebatch.md#writebatchupdate) | | Updates fields in the document referred to by this [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist.Nested fields can be update by providing dot-separated field path strings or by providing FieldPath objects. | - -## WriteBatch.commit() - -Commits all of the writes in this write batch as a single atomic unit. - -The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. - -Signature: - -```typescript -commit(): Promise; -``` -Returns: - -Promise<void> - -A `Promise` resolved once all of the writes in the batch have been successfully written to the backend as an atomic unit (note that it won't resolve while you're offline). - -## WriteBatch.delete() - -Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). - -Signature: - -```typescript -delete(documentRef: DocumentReference): WriteBatch; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to the document to be deleted. | - -Returns: - -[WriteBatch](./firestore_lite.writebatch.md#writebatch_class) - -This `WriteBatch` instance. Used for chaining method calls. - -## WriteBatch.set() - -Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. - -Signature: - -```typescript -set(documentRef: DocumentReference, data: WithFieldValue): WriteBatch; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | -| data | [WithFieldValue](./firestore_lite.md#withfieldvalue)<T> | An object of the fields and values for the document. | - -Returns: - -[WriteBatch](./firestore_lite.writebatch.md#writebatch_class) - -This `WriteBatch` instance. Used for chaining method calls. - -## WriteBatch.set() - -Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. - -Signature: - -```typescript -set(documentRef: DocumentReference, data: PartialWithFieldValue, options: SetOptions): WriteBatch; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | -| data | [PartialWithFieldValue](./firestore_lite.md#partialwithfieldvalue)<T> | An object of the fields and values for the document. | -| options | [SetOptions](./firestore_lite.md#setoptions) | An object to configure the set behavior. | - -Returns: - -[WriteBatch](./firestore_lite.writebatch.md#writebatch_class) - -This `WriteBatch` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not a valid Firestore document. - -## WriteBatch.update() - -Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. - -Signature: - -```typescript -update(documentRef: DocumentReference, data: UpdateData): WriteBatch; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be updated. | -| data | [UpdateData](./firestore_lite.md#updatedata)<T> | An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document. | - -Returns: - -[WriteBatch](./firestore_lite.writebatch.md#writebatch_class) - -This `WriteBatch` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not valid Firestore data. - -## WriteBatch.update() - -Updates fields in the document referred to by this [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. - -Nested fields can be update by providing dot-separated field path strings or by providing `FieldPath` objects. - -Signature: - -```typescript -update(documentRef: DocumentReference, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): WriteBatch; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to the document to be updated. | -| field | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The first field to update. | -| value | unknown | The first value. | -| moreFieldsAndValues | unknown\[\] | Additional key value pairs. | - -Returns: - -[WriteBatch](./firestore_lite.writebatch.md#writebatch_class) - -This `WriteBatch` instance. Used for chaining method calls. - -## Exceptions - -Error - If the provided input is not valid Firestore data. - diff --git a/docs-devsite/functions.functions.md b/docs-devsite/functions.functions.md deleted file mode 100644 index da5e0585f45..00000000000 --- a/docs-devsite/functions.functions.md +++ /dev/null @@ -1,57 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Functions interface -A `Functions` instance. - -Signature: - -```typescript -export interface Functions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [app](./functions.functions.md#functionsapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this Functions instance is associated with. | -| [customDomain](./functions.functions.md#functionscustomdomain) | string \| null | A custom domain hosting the callable Cloud Functions. ex: https://mydomain.com | -| [region](./functions.functions.md#functionsregion) | string | The region the callable Cloud Functions are located in. Default is us-central-1. | - -## Functions.app - -The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `Functions` instance is associated with. - -Signature: - -```typescript -app: FirebaseApp; -``` - -## Functions.customDomain - -A custom domain hosting the callable Cloud Functions. ex: https://mydomain.com - -Signature: - -```typescript -customDomain: string | null; -``` - -## Functions.region - -The region the callable Cloud Functions are located in. Default is `us-central-1`. - -Signature: - -```typescript -region: string; -``` diff --git a/docs-devsite/functions.functionserror.md b/docs-devsite/functions.functionserror.md deleted file mode 100644 index 3be96745b4c..00000000000 --- a/docs-devsite/functions.functionserror.md +++ /dev/null @@ -1,47 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FunctionsError interface -An error returned by the Firebase Functions client SDK. - -Signature: - -```typescript -export interface FunctionsError extends FirebaseError -``` -Extends: [FirebaseError](./util.firebaseerror.md#firebaseerror_class) - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [code](./functions.functionserror.md#functionserrorcode) | [FunctionsErrorCode](./functions.md#functionserrorcode) | A standard error code that will be returned to the client. This also determines the HTTP status code of the response, as defined in code.proto. | -| [details](./functions.functionserror.md#functionserrordetails) | unknown | Extra data to be converted to JSON and included in the error response. | - -## FunctionsError.code - -A standard error code that will be returned to the client. This also determines the HTTP status code of the response, as defined in code.proto. - -Signature: - -```typescript -readonly code: FunctionsErrorCode; -``` - -## FunctionsError.details - -Extra data to be converted to JSON and included in the error response. - -Signature: - -```typescript -readonly details?: unknown; -``` diff --git a/docs-devsite/functions.httpscallableoptions.md b/docs-devsite/functions.httpscallableoptions.md deleted file mode 100644 index cb84abf2526..00000000000 --- a/docs-devsite/functions.httpscallableoptions.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# HttpsCallableOptions interface -An interface for metadata about how calls should be executed. - -Signature: - -```typescript -export interface HttpsCallableOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [timeout](./functions.httpscallableoptions.md#httpscallableoptionstimeout) | number | Time in milliseconds after which to cancel if there is no response. Default is 70000. | - -## HttpsCallableOptions.timeout - -Time in milliseconds after which to cancel if there is no response. Default is 70000. - -Signature: - -```typescript -timeout?: number; -``` diff --git a/docs-devsite/functions.httpscallableresult.md b/docs-devsite/functions.httpscallableresult.md deleted file mode 100644 index 6c9877f423b..00000000000 --- a/docs-devsite/functions.httpscallableresult.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# HttpsCallableResult interface -An `HttpsCallableResult` wraps a single result from a function call. - -Signature: - -```typescript -export interface HttpsCallableResult -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [data](./functions.httpscallableresult.md#httpscallableresultdata) | ResponseData | Data returned from callable function. | - -## HttpsCallableResult.data - -Data returned from callable function. - -Signature: - -```typescript -readonly data: ResponseData; -``` diff --git a/docs-devsite/functions.md b/docs-devsite/functions.md deleted file mode 100644 index 35b5087e08e..00000000000 --- a/docs-devsite/functions.md +++ /dev/null @@ -1,162 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# functions package -Cloud Functions for Firebase - -## Functions - -| Function | Description | -| --- | --- | -| function(app...) | -| [getFunctions(app, regionOrCustomDomain)](./functions.md#getfunctions) | Returns a [Functions](./functions.functions.md#functions_interface) instance for the given app. | -| function(functionsInstance...) | -| [connectFunctionsEmulator(functionsInstance, host, port)](./functions.md#connectfunctionsemulator) | Modify this instance to communicate with the Cloud Functions emulator.Note: this must be called before this instance has been used to do any operations. | -| [httpsCallable(functionsInstance, name, options)](./functions.md#httpscallable) | Returns a reference to the callable HTTPS trigger with the given name. | -| [httpsCallableFromURL(functionsInstance, url, options)](./functions.md#httpscallablefromurl) | Returns a reference to the callable HTTPS trigger with the specified url. | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [Functions](./functions.functions.md#functions_interface) | A Functions instance. | -| [FunctionsError](./functions.functionserror.md#functionserror_interface) | An error returned by the Firebase Functions client SDK. | -| [HttpsCallableOptions](./functions.httpscallableoptions.md#httpscallableoptions_interface) | An interface for metadata about how calls should be executed. | -| [HttpsCallableResult](./functions.httpscallableresult.md#httpscallableresult_interface) | An HttpsCallableResult wraps a single result from a function call. | - -## Type Aliases - -| Type Alias | Description | -| --- | --- | -| [FunctionsErrorCode](./functions.md#functionserrorcode) | The set of Firebase Functions status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.mdPossible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (e.g. an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation. | -| [FunctionsErrorCodeCore](./functions.md#functionserrorcodecore) | Functions error code string appended after "functions/" product prefix. See [FunctionsErrorCode](./functions.md#functionserrorcode) for full documentation of codes. | -| [HttpsCallable](./functions.md#httpscallable) | A reference to a "callable" HTTP trigger in Google Cloud Functions. | - -## getFunctions() - -Returns a [Functions](./functions.functions.md#functions_interface) instance for the given app. - -Signature: - -```typescript -export declare function getFunctions(app?: FirebaseApp, regionOrCustomDomain?: string): Functions; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to use. | -| regionOrCustomDomain | string | one of: a) The region the callable functions are located in (ex: us-central1) b) A custom domain hosting the callable functions (ex: https://mydomain.com) | - -Returns: - -[Functions](./functions.functions.md#functions_interface) - -## connectFunctionsEmulator() - -Modify this instance to communicate with the Cloud Functions emulator. - -Note: this must be called before this instance has been used to do any operations. - -Signature: - -```typescript -export declare function connectFunctionsEmulator(functionsInstance: Functions, host: string, port: number): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| functionsInstance | [Functions](./functions.functions.md#functions_interface) | | -| host | string | The emulator host (ex: localhost) | -| port | number | The emulator port (ex: 5001) | - -Returns: - -void - -## httpsCallable() - -Returns a reference to the callable HTTPS trigger with the given name. - -Signature: - -```typescript -export declare function httpsCallable(functionsInstance: Functions, name: string, options?: HttpsCallableOptions): HttpsCallable; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| functionsInstance | [Functions](./functions.functions.md#functions_interface) | | -| name | string | The name of the trigger. | -| options | [HttpsCallableOptions](./functions.httpscallableoptions.md#httpscallableoptions_interface) | | - -Returns: - -[HttpsCallable](./functions.md#httpscallable)<RequestData, ResponseData> - -## httpsCallableFromURL() - -Returns a reference to the callable HTTPS trigger with the specified url. - -Signature: - -```typescript -export declare function httpsCallableFromURL(functionsInstance: Functions, url: string, options?: HttpsCallableOptions): HttpsCallable; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| functionsInstance | [Functions](./functions.functions.md#functions_interface) | | -| url | string | The url of the trigger. | -| options | [HttpsCallableOptions](./functions.httpscallableoptions.md#httpscallableoptions_interface) | | - -Returns: - -[HttpsCallable](./functions.md#httpscallable)<RequestData, ResponseData> - -## FunctionsErrorCode - -The set of Firebase Functions status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.md - -Possible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (e.g. an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation. - -Signature: - -```typescript -export declare type FunctionsErrorCode = `functions/${FunctionsErrorCodeCore}`; -``` - -## FunctionsErrorCodeCore - -Functions error code string appended after "functions/" product prefix. See [FunctionsErrorCode](./functions.md#functionserrorcode) for full documentation of codes. - -Signature: - -```typescript -export declare type FunctionsErrorCodeCore = 'ok' | 'cancelled' | 'unknown' | 'invalid-argument' | 'deadline-exceeded' | 'not-found' | 'already-exists' | 'permission-denied' | 'resource-exhausted' | 'failed-precondition' | 'aborted' | 'out-of-range' | 'unimplemented' | 'internal' | 'unavailable' | 'data-loss' | 'unauthenticated'; -``` - -## HttpsCallable - -A reference to a "callable" HTTP trigger in Google Cloud Functions. - -Signature: - -```typescript -export declare type HttpsCallable = (data?: RequestData | null) => Promise>; -``` diff --git a/docs-devsite/index.md b/docs-devsite/index.md deleted file mode 100644 index e19f70906ef..00000000000 --- a/docs-devsite/index.md +++ /dev/null @@ -1,30 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# API Reference - -## Packages - -| Package | Description | -| --- | --- | -| [@firebase/analytics](./analytics.md#analytics_package) | Firebase Analytics | -| [@firebase/app](./app.md#app_package) | Firebase App | -| [@firebase/app-check](./app-check.md#app-check_package) | Firebase App Check | -| [@firebase/auth](./auth.md#auth_package) | Firebase Authentication | -| [@firebase/database](./database.md#database_package) | Firebase Realtime Database | -| [@firebase/firestore](./firestore.md#firestore_package) | Cloud Firestore | -| [@firebase/functions](./functions.md#functions_package) | Cloud Functions for Firebase | -| [@firebase/installations](./installations.md#installations_package) | Firebase Installations | -| [@firebase/messaging](./messaging.md#messaging_package) | Firebase Cloud Messaging | -| [@firebase/performance](./performance.md#performance_package) | Firebase Performance Monitoring | -| [@firebase/remote-config](./remote-config.md#remote-config_package) | Firebase Remote Config | -| [@firebase/storage](./storage.md#storage_package) | Cloud Storage for Firebase | - diff --git a/docs-devsite/installations.installations.md b/docs-devsite/installations.installations.md deleted file mode 100644 index 4c1107e0354..00000000000 --- a/docs-devsite/installations.installations.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Installations interface -Public interface of the Firebase Installations SDK. - -Signature: - -```typescript -export interface Installations -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [app](./installations.installations.md#installationsapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this Installations instance is associated with. | - -## Installations.app - -The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `Installations` instance is associated with. - -Signature: - -```typescript -app: FirebaseApp; -``` diff --git a/docs-devsite/installations.md b/docs-devsite/installations.md deleted file mode 100644 index 1ef8b80b00e..00000000000 --- a/docs-devsite/installations.md +++ /dev/null @@ -1,162 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# installations package -Firebase Installations - -## Functions - -| Function | Description | -| --- | --- | -| function(app...) | -| [getInstallations(app)](./installations.md#getinstallations) | Returns an instance of [Installations](./installations.installations.md#installations_interface) associated with the given [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. | -| function(installations...) | -| [deleteInstallations(installations)](./installations.md#deleteinstallations) | Deletes the Firebase Installation and all associated data. | -| [getId(installations)](./installations.md#getid) | Creates a Firebase Installation if there isn't one for the app and returns the Installation ID. | -| [getToken(installations, forceRefresh)](./installations.md#gettoken) | Returns a Firebase Installations auth token, identifying the current Firebase Installation. | -| [onIdChange(installations, callback)](./installations.md#onidchange) | Sets a new callback that will get called when Installation ID changes. Returns an unsubscribe function that will remove the callback when called. | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [Installations](./installations.installations.md#installations_interface) | Public interface of the Firebase Installations SDK. | - -## Type Aliases - -| Type Alias | Description | -| --- | --- | -| [IdChangeCallbackFn](./installations.md#idchangecallbackfn) | An user defined callback function that gets called when Installations ID changes. | -| [IdChangeUnsubscribeFn](./installations.md#idchangeunsubscribefn) | Unsubscribe a callback function previously added via [IdChangeCallbackFn](./installations.md#idchangecallbackfn). | - -## getInstallations() - -Returns an instance of [Installations](./installations.installations.md#installations_interface) associated with the given [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. - -Signature: - -```typescript -export declare function getInstallations(app?: FirebaseApp): Installations; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. | - -Returns: - -[Installations](./installations.installations.md#installations_interface) - -## deleteInstallations() - -Deletes the Firebase Installation and all associated data. - -Signature: - -```typescript -export declare function deleteInstallations(installations: Installations): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| installations | [Installations](./installations.installations.md#installations_interface) | The Installations instance. | - -Returns: - -Promise<void> - -## getId() - -Creates a Firebase Installation if there isn't one for the app and returns the Installation ID. - -Signature: - -```typescript -export declare function getId(installations: Installations): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| installations | [Installations](./installations.installations.md#installations_interface) | The Installations instance. | - -Returns: - -Promise<string> - -## getToken() - -Returns a Firebase Installations auth token, identifying the current Firebase Installation. - -Signature: - -```typescript -export declare function getToken(installations: Installations, forceRefresh?: boolean): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| installations | [Installations](./installations.installations.md#installations_interface) | The Installations instance. | -| forceRefresh | boolean | Force refresh regardless of token expiration. | - -Returns: - -Promise<string> - -## onIdChange() - -Sets a new callback that will get called when Installation ID changes. Returns an unsubscribe function that will remove the callback when called. - -Signature: - -```typescript -export declare function onIdChange(installations: Installations, callback: IdChangeCallbackFn): IdChangeUnsubscribeFn; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| installations | [Installations](./installations.installations.md#installations_interface) | The Installations instance. | -| callback | [IdChangeCallbackFn](./installations.md#idchangecallbackfn) | The callback function that is invoked when FID changes. | - -Returns: - -[IdChangeUnsubscribeFn](./installations.md#idchangeunsubscribefn) - -A function that can be called to unsubscribe. - -## IdChangeCallbackFn - -An user defined callback function that gets called when Installations ID changes. - -Signature: - -```typescript -export declare type IdChangeCallbackFn = (installationId: string) => void; -``` - -## IdChangeUnsubscribeFn - -Unsubscribe a callback function previously added via [IdChangeCallbackFn](./installations.md#idchangecallbackfn). - -Signature: - -```typescript -export declare type IdChangeUnsubscribeFn = () => void; -``` diff --git a/docs-devsite/messaging.md b/docs-devsite/messaging.md deleted file mode 100644 index ffbdd9ee3d8..00000000000 --- a/docs-devsite/messaging.md +++ /dev/null @@ -1,19 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# messaging package -Firebase Cloud Messaging - -| Entry Point | Description | -| --- | --- | -| [/](./messaging_.md#@firebase/messaging) | | -| [/sw](./messaging_sw.md#@firebase/messaging/sw) | | - diff --git a/docs-devsite/messaging_.fcmoptions.md b/docs-devsite/messaging_.fcmoptions.md deleted file mode 100644 index 15f6123bae2..00000000000 --- a/docs-devsite/messaging_.fcmoptions.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FcmOptions interface -Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) - -Signature: - -```typescript -export interface FcmOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [analyticsLabel](./messaging_.fcmoptions.md#fcmoptionsanalyticslabel) | string | The label associated with the message's analytics data. | -| [link](./messaging_.fcmoptions.md#fcmoptionslink) | string | The link to open when the user clicks on the notification. | - -## FcmOptions.analyticsLabel - -The label associated with the message's analytics data. - -Signature: - -```typescript -analyticsLabel?: string; -``` - -## FcmOptions.link - -The link to open when the user clicks on the notification. - -Signature: - -```typescript -link?: string; -``` diff --git a/docs-devsite/messaging_.gettokenoptions.md b/docs-devsite/messaging_.gettokenoptions.md deleted file mode 100644 index ed506fb5666..00000000000 --- a/docs-devsite/messaging_.gettokenoptions.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# GetTokenOptions interface -Options for [getToken()](./messaging_.md#gettoken) - -Signature: - -```typescript -export interface GetTokenOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [serviceWorkerRegistration](./messaging_.gettokenoptions.md#gettokenoptionsserviceworkerregistration) | ServiceWorkerRegistration | The service worker registration for receiving push messaging. If the registration is not provided explicitly, you need to have a firebase-messaging-sw.js at your root location. See [Retrieve the current registration token](https://firebase.google.com/docs/cloud-messaging/js/client#retrieve-the-current-registration-token) for more details. | -| [vapidKey](./messaging_.gettokenoptions.md#gettokenoptionsvapidkey) | string | The public server key provided to push services. It is used to authenticate the push subscribers to receive push messages only from sending servers that hold the corresponding private key. If it is not provided, a default VAPID key is used. Note that some push services (Chrome Push Service) require a non-default VAPID key. Therefore, it is recommended to generate and import a VAPID key for your project with [Configure Web Credentials with FCM](https://firebase.google.com/docs/cloud-messaging/js/client#configure_web_credentials_with_fcm). See [The Web Push Protocol](https://developers.google.com/web/fundamentals/push-notifications/web-push-protocol) for details on web push services. | - -## GetTokenOptions.serviceWorkerRegistration - -The service worker registration for receiving push messaging. If the registration is not provided explicitly, you need to have a `firebase-messaging-sw.js` at your root location. See [Retrieve the current registration token](https://firebase.google.com/docs/cloud-messaging/js/client#retrieve-the-current-registration-token) for more details. - -Signature: - -```typescript -serviceWorkerRegistration?: ServiceWorkerRegistration; -``` - -## GetTokenOptions.vapidKey - -The public server key provided to push services. It is used to authenticate the push subscribers to receive push messages only from sending servers that hold the corresponding private key. If it is not provided, a default VAPID key is used. Note that some push services (Chrome Push Service) require a non-default VAPID key. Therefore, it is recommended to generate and import a VAPID key for your project with [Configure Web Credentials with FCM](https://firebase.google.com/docs/cloud-messaging/js/client#configure_web_credentials_with_fcm). See [The Web Push Protocol](https://developers.google.com/web/fundamentals/push-notifications/web-push-protocol) for details on web push services. - -Signature: - -```typescript -vapidKey?: string; -``` diff --git a/docs-devsite/messaging_.md b/docs-devsite/messaging_.md deleted file mode 100644 index ad04429ac94..00000000000 --- a/docs-devsite/messaging_.md +++ /dev/null @@ -1,143 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# @firebase/messaging - -## Functions - -| Function | Description | -| --- | --- | -| function(app...) | -| [getMessaging(app)](./messaging_.md#getmessaging) | Retrieves a Firebase Cloud Messaging instance. | -| function(messaging...) | -| [deleteToken(messaging)](./messaging_.md#deletetoken) | Deletes the registration token associated with this [Messaging](./messaging_.messaging.md#messaging_interface) instance and unsubscribes the [Messaging](./messaging_.messaging.md#messaging_interface) instance from the push subscription. | -| [getToken(messaging, options)](./messaging_.md#gettoken) | Subscribes the [Messaging](./messaging_.messaging.md#messaging_interface) instance to push notifications. Returns an Firebase Cloud Messaging registration token that can be used to send push messages to that [Messaging](./messaging_.messaging.md#messaging_interface) instance.If a notification permission isn't already granted, this method asks the user for permission. The returned promise rejects if the user does not allow the app to show notifications. | -| [onMessage(messaging, nextOrObserver)](./messaging_.md#onmessage) | When a push message is received and the user is currently on a page for your origin, the message is passed to the page and an onMessage() event is dispatched with the payload of the push message. | -| function() | -| [isSupported()](./messaging_.md#issupported) | Checks if all required APIs exist in the browser. | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [FcmOptions](./messaging_.fcmoptions.md#fcmoptions_interface) | Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) | -| [GetTokenOptions](./messaging_.gettokenoptions.md#gettokenoptions_interface) | Options for [getToken()](./messaging_.md#gettoken) | -| [MessagePayload](./messaging_.messagepayload.md#messagepayload_interface) | Message payload that contains the notification payload that is represented with [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) and the data payload that contains an arbitrary number of key-value pairs sent by developers through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) | -| [Messaging](./messaging_.messaging.md#messaging_interface) | Public interface of the Firebase Cloud Messaging SDK. | -| [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) | Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) | - -## getMessaging() - -Retrieves a Firebase Cloud Messaging instance. - -Signature: - -```typescript -export declare function getMessagingInWindow(app?: FirebaseApp): Messaging; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | | - -Returns: - -[Messaging](./messaging_.messaging.md#messaging_interface) - -The Firebase Cloud Messaging instance associated with the provided firebase app. - -## deleteToken() - -Deletes the registration token associated with this [Messaging](./messaging_.messaging.md#messaging_interface) instance and unsubscribes the [Messaging](./messaging_.messaging.md#messaging_interface) instance from the push subscription. - -Signature: - -```typescript -export declare function deleteToken(messaging: Messaging): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| messaging | [Messaging](./messaging_.messaging.md#messaging_interface) | The [Messaging](./messaging_.messaging.md#messaging_interface) instance. | - -Returns: - -Promise<boolean> - -The promise resolves when the token has been successfully deleted. - -## getToken() - -Subscribes the [Messaging](./messaging_.messaging.md#messaging_interface) instance to push notifications. Returns an Firebase Cloud Messaging registration token that can be used to send push messages to that [Messaging](./messaging_.messaging.md#messaging_interface) instance. - -If a notification permission isn't already granted, this method asks the user for permission. The returned promise rejects if the user does not allow the app to show notifications. - -Signature: - -```typescript -export declare function getToken(messaging: Messaging, options?: GetTokenOptions): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| messaging | [Messaging](./messaging_.messaging.md#messaging_interface) | The [Messaging](./messaging_.messaging.md#messaging_interface) instance. | -| options | [GetTokenOptions](./messaging_.gettokenoptions.md#gettokenoptions_interface) | Provides an optional vapid key and an optinoal service worker registration | - -Returns: - -Promise<string> - -The promise resolves with an FCM registration token. - -## onMessage() - -When a push message is received and the user is currently on a page for your origin, the message is passed to the page and an `onMessage()` event is dispatched with the payload of the push message. - -Signature: - -```typescript -export declare function onMessage(messaging: Messaging, nextOrObserver: NextFn | Observer): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| messaging | [Messaging](./messaging_.messaging.md#messaging_interface) | The [Messaging](./messaging_.messaging.md#messaging_interface) instance. | -| nextOrObserver | [NextFn](./util.md#nextfn)<[MessagePayload](./messaging_.messagepayload.md#messagepayload_interface)> \| [Observer](./util.observer.md#observer_interface)<[MessagePayload](./messaging_.messagepayload.md#messagepayload_interface)> | This function, or observer object with next defined, is called when a message is received and the user is currently viewing your page. | - -Returns: - -[Unsubscribe](./util.md#unsubscribe) - -To stop listening for messages execute this returned function. - -## isSupported() - -Checks if all required APIs exist in the browser. - -Signature: - -```typescript -export declare function isWindowSupported(): Promise; -``` -Returns: - -Promise<boolean> - -a Promise that resolves to a boolean. - diff --git a/docs-devsite/messaging_.messagepayload.md b/docs-devsite/messaging_.messagepayload.md deleted file mode 100644 index 1a944ebbc52..00000000000 --- a/docs-devsite/messaging_.messagepayload.md +++ /dev/null @@ -1,92 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# MessagePayload interface -Message payload that contains the notification payload that is represented with [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) and the data payload that contains an arbitrary number of key-value pairs sent by developers through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) - -Signature: - -```typescript -export interface MessagePayload -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [collapseKey](./messaging_.messagepayload.md#messagepayloadcollapsekey) | string | The collapse key of the message. See [Non-collapsible and collapsible messages](https://firebase.google.com/docs/cloud-messaging/concept-options#collapsible_and_non-collapsible_messages) | -| [data](./messaging_.messagepayload.md#messagepayloaddata) | { \[key: string\]: string; } | Arbitrary key/value payload. | -| [fcmOptions](./messaging_.messagepayload.md#messagepayloadfcmoptions) | [FcmOptions](./messaging_.fcmoptions.md#fcmoptions_interface) | Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) | -| [from](./messaging_.messagepayload.md#messagepayloadfrom) | string | The sender of this message. | -| [messageId](./messaging_.messagepayload.md#messagepayloadmessageid) | string | The message id of a message. | -| [notification](./messaging_.messagepayload.md#messagepayloadnotification) | [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) | Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) | - -## MessagePayload.collapseKey - -The collapse key of the message. See [Non-collapsible and collapsible messages](https://firebase.google.com/docs/cloud-messaging/concept-options#collapsible_and_non-collapsible_messages) - -Signature: - -```typescript -collapseKey: string; -``` - -## MessagePayload.data - -Arbitrary key/value payload. - -Signature: - -```typescript -data?: { - [key: string]: string; - }; -``` - -## MessagePayload.fcmOptions - -Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) - -Signature: - -```typescript -fcmOptions?: FcmOptions; -``` - -## MessagePayload.from - -The sender of this message. - -Signature: - -```typescript -from: string; -``` - -## MessagePayload.messageId - -The message id of a message. - -Signature: - -```typescript -messageId: string; -``` - -## MessagePayload.notification - -Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) - -Signature: - -```typescript -notification?: NotificationPayload; -``` diff --git a/docs-devsite/messaging_.messaging.md b/docs-devsite/messaging_.messaging.md deleted file mode 100644 index 8d16b75467a..00000000000 --- a/docs-devsite/messaging_.messaging.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Messaging interface -Public interface of the Firebase Cloud Messaging SDK. - -Signature: - -```typescript -export interface Messaging -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [app](./messaging_.messaging.md#messagingapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this Messaging instance is associated with. | - -## Messaging.app - -The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `Messaging` instance is associated with. - -Signature: - -```typescript -app: FirebaseApp; -``` diff --git a/docs-devsite/messaging_.notificationpayload.md b/docs-devsite/messaging_.notificationpayload.md deleted file mode 100644 index 5978a55b6bf..00000000000 --- a/docs-devsite/messaging_.notificationpayload.md +++ /dev/null @@ -1,68 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# NotificationPayload interface -Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) - -Signature: - -```typescript -export interface NotificationPayload -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [body](./messaging_.notificationpayload.md#notificationpayloadbody) | string | The notification's body text. | -| [icon](./messaging_.notificationpayload.md#notificationpayloadicon) | string | The URL to use for the notification's icon. If you don't send this key in the request, FCM displays the launcher icon specified in your app manifest. | -| [image](./messaging_.notificationpayload.md#notificationpayloadimage) | string | The URL of an image that is downloaded on the device and displayed in the notification. | -| [title](./messaging_.notificationpayload.md#notificationpayloadtitle) | string | The notification's title. | - -## NotificationPayload.body - -The notification's body text. - -Signature: - -```typescript -body?: string; -``` - -## NotificationPayload.icon - -The URL to use for the notification's icon. If you don't send this key in the request, FCM displays the launcher icon specified in your app manifest. - -Signature: - -```typescript -icon?: string; -``` - -## NotificationPayload.image - -The URL of an image that is downloaded on the device and displayed in the notification. - -Signature: - -```typescript -image?: string; -``` - -## NotificationPayload.title - -The notification's title. - -Signature: - -```typescript -title?: string; -``` diff --git a/docs-devsite/messaging_sw.fcmoptions.md b/docs-devsite/messaging_sw.fcmoptions.md deleted file mode 100644 index 55fdddaa0e3..00000000000 --- a/docs-devsite/messaging_sw.fcmoptions.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FcmOptions interface -Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) - -Signature: - -```typescript -export interface FcmOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [analyticsLabel](./messaging_sw.fcmoptions.md#fcmoptionsanalyticslabel) | string | The label associated with the message's analytics data. | -| [link](./messaging_sw.fcmoptions.md#fcmoptionslink) | string | The link to open when the user clicks on the notification. | - -## FcmOptions.analyticsLabel - -The label associated with the message's analytics data. - -Signature: - -```typescript -analyticsLabel?: string; -``` - -## FcmOptions.link - -The link to open when the user clicks on the notification. - -Signature: - -```typescript -link?: string; -``` diff --git a/docs-devsite/messaging_sw.gettokenoptions.md b/docs-devsite/messaging_sw.gettokenoptions.md deleted file mode 100644 index 5e724513a02..00000000000 --- a/docs-devsite/messaging_sw.gettokenoptions.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# GetTokenOptions interface -Options for [getToken()](./messaging_.md#gettoken) - -Signature: - -```typescript -export interface GetTokenOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [serviceWorkerRegistration](./messaging_sw.gettokenoptions.md#gettokenoptionsserviceworkerregistration) | ServiceWorkerRegistration | The service worker registration for receiving push messaging. If the registration is not provided explicitly, you need to have a firebase-messaging-sw.js at your root location. See [Retrieve the current registration token](https://firebase.google.com/docs/cloud-messaging/js/client#retrieve-the-current-registration-token) for more details. | -| [vapidKey](./messaging_sw.gettokenoptions.md#gettokenoptionsvapidkey) | string | The public server key provided to push services. It is used to authenticate the push subscribers to receive push messages only from sending servers that hold the corresponding private key. If it is not provided, a default VAPID key is used. Note that some push services (Chrome Push Service) require a non-default VAPID key. Therefore, it is recommended to generate and import a VAPID key for your project with [Configure Web Credentials with FCM](https://firebase.google.com/docs/cloud-messaging/js/client#configure_web_credentials_with_fcm). See [The Web Push Protocol](https://developers.google.com/web/fundamentals/push-notifications/web-push-protocol) for details on web push services. | - -## GetTokenOptions.serviceWorkerRegistration - -The service worker registration for receiving push messaging. If the registration is not provided explicitly, you need to have a `firebase-messaging-sw.js` at your root location. See [Retrieve the current registration token](https://firebase.google.com/docs/cloud-messaging/js/client#retrieve-the-current-registration-token) for more details. - -Signature: - -```typescript -serviceWorkerRegistration?: ServiceWorkerRegistration; -``` - -## GetTokenOptions.vapidKey - -The public server key provided to push services. It is used to authenticate the push subscribers to receive push messages only from sending servers that hold the corresponding private key. If it is not provided, a default VAPID key is used. Note that some push services (Chrome Push Service) require a non-default VAPID key. Therefore, it is recommended to generate and import a VAPID key for your project with [Configure Web Credentials with FCM](https://firebase.google.com/docs/cloud-messaging/js/client#configure_web_credentials_with_fcm). See [The Web Push Protocol](https://developers.google.com/web/fundamentals/push-notifications/web-push-protocol) for details on web push services. - -Signature: - -```typescript -vapidKey?: string; -``` diff --git a/docs-devsite/messaging_sw.md b/docs-devsite/messaging_sw.md deleted file mode 100644 index 0950fc61034..00000000000 --- a/docs-devsite/messaging_sw.md +++ /dev/null @@ -1,116 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# @firebase/messaging/sw - -## Functions - -| Function | Description | -| --- | --- | -| function(app...) | -| [getMessaging(app)](./messaging_sw.md#getmessaging) | Retrieves a Firebase Cloud Messaging instance. | -| function(messaging...) | -| [experimentalSetDeliveryMetricsExportedToBigQueryEnabled(messaging, enable)](./messaging_sw.md#experimentalsetdeliverymetricsexportedtobigqueryenabled) | Enables or disables Firebase Cloud Messaging message delivery metrics export to BigQuery. By default, message delivery metrics are not exported to BigQuery. Use this method to enable or disable the export at runtime. | -| [onBackgroundMessage(messaging, nextOrObserver)](./messaging_sw.md#onbackgroundmessage) | Called when a message is received while the app is in the background. An app is considered to be in the background if no active window is displayed. | -| function() | -| [isSupported()](./messaging_sw.md#issupported) | Checks whether all required APIs exist within SW Context | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [FcmOptions](./messaging_sw.fcmoptions.md#fcmoptions_interface) | Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) | -| [GetTokenOptions](./messaging_sw.gettokenoptions.md#gettokenoptions_interface) | Options for [getToken()](./messaging_.md#gettoken) | -| [MessagePayload](./messaging_sw.messagepayload.md#messagepayload_interface) | Message payload that contains the notification payload that is represented with [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) and the data payload that contains an arbitrary number of key-value pairs sent by developers through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) | -| [Messaging](./messaging_sw.messaging.md#messaging_interface) | Public interface of the Firebase Cloud Messaging SDK. | -| [NotificationPayload](./messaging_sw.notificationpayload.md#notificationpayload_interface) | Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) | - -## getMessaging() - -Retrieves a Firebase Cloud Messaging instance. - -Signature: - -```typescript -export declare function getMessagingInSw(app?: FirebaseApp): Messaging; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | | - -Returns: - -[Messaging](./messaging_.messaging.md#messaging_interface) - -The Firebase Cloud Messaging instance associated with the provided firebase app. - -## experimentalSetDeliveryMetricsExportedToBigQueryEnabled() - -Enables or disables Firebase Cloud Messaging message delivery metrics export to BigQuery. By default, message delivery metrics are not exported to BigQuery. Use this method to enable or disable the export at runtime. - -Signature: - -```typescript -export declare function experimentalSetDeliveryMetricsExportedToBigQueryEnabled(messaging: Messaging, enable: boolean): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| messaging | [Messaging](./messaging_.messaging.md#messaging_interface) | The FirebaseMessaging instance. | -| enable | boolean | Whether Firebase Cloud Messaging should export message delivery metrics to BigQuery. | - -Returns: - -void - -## onBackgroundMessage() - -Called when a message is received while the app is in the background. An app is considered to be in the background if no active window is displayed. - -Signature: - -```typescript -export declare function onBackgroundMessage(messaging: Messaging, nextOrObserver: NextFn | Observer): Unsubscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| messaging | [Messaging](./messaging_.messaging.md#messaging_interface) | The [Messaging](./messaging_.messaging.md#messaging_interface) instance. | -| nextOrObserver | [NextFn](./util.md#nextfn)<[MessagePayload](./messaging_.messagepayload.md#messagepayload_interface)> \| [Observer](./util.observer.md#observer_interface)<[MessagePayload](./messaging_.messagepayload.md#messagepayload_interface)> | This function, or observer object with next defined, is called when a message is received and the app is currently in the background. | - -Returns: - -[Unsubscribe](./util.md#unsubscribe) - -To stop listening for messages execute this returned function - -## isSupported() - -Checks whether all required APIs exist within SW Context - -Signature: - -```typescript -export declare function isSwSupported(): Promise; -``` -Returns: - -Promise<boolean> - -a Promise that resolves to a boolean. - diff --git a/docs-devsite/messaging_sw.messagepayload.md b/docs-devsite/messaging_sw.messagepayload.md deleted file mode 100644 index 2037bb0016d..00000000000 --- a/docs-devsite/messaging_sw.messagepayload.md +++ /dev/null @@ -1,92 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# MessagePayload interface -Message payload that contains the notification payload that is represented with [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) and the data payload that contains an arbitrary number of key-value pairs sent by developers through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) - -Signature: - -```typescript -export interface MessagePayload -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [collapseKey](./messaging_sw.messagepayload.md#messagepayloadcollapsekey) | string | The collapse key of the message. See [Non-collapsible and collapsible messages](https://firebase.google.com/docs/cloud-messaging/concept-options#collapsible_and_non-collapsible_messages) | -| [data](./messaging_sw.messagepayload.md#messagepayloaddata) | { \[key: string\]: string; } | Arbitrary key/value payload. | -| [fcmOptions](./messaging_sw.messagepayload.md#messagepayloadfcmoptions) | [FcmOptions](./messaging_.fcmoptions.md#fcmoptions_interface) | Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) | -| [from](./messaging_sw.messagepayload.md#messagepayloadfrom) | string | The sender of this message. | -| [messageId](./messaging_sw.messagepayload.md#messagepayloadmessageid) | string | The message id of a message. | -| [notification](./messaging_sw.messagepayload.md#messagepayloadnotification) | [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) | Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) | - -## MessagePayload.collapseKey - -The collapse key of the message. See [Non-collapsible and collapsible messages](https://firebase.google.com/docs/cloud-messaging/concept-options#collapsible_and_non-collapsible_messages) - -Signature: - -```typescript -collapseKey: string; -``` - -## MessagePayload.data - -Arbitrary key/value payload. - -Signature: - -```typescript -data?: { - [key: string]: string; - }; -``` - -## MessagePayload.fcmOptions - -Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) - -Signature: - -```typescript -fcmOptions?: FcmOptions; -``` - -## MessagePayload.from - -The sender of this message. - -Signature: - -```typescript -from: string; -``` - -## MessagePayload.messageId - -The message id of a message. - -Signature: - -```typescript -messageId: string; -``` - -## MessagePayload.notification - -Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) - -Signature: - -```typescript -notification?: NotificationPayload; -``` diff --git a/docs-devsite/messaging_sw.messaging.md b/docs-devsite/messaging_sw.messaging.md deleted file mode 100644 index cfd15fe9aaf..00000000000 --- a/docs-devsite/messaging_sw.messaging.md +++ /dev/null @@ -1,35 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Messaging interface -Public interface of the Firebase Cloud Messaging SDK. - -Signature: - -```typescript -export interface Messaging -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [app](./messaging_sw.messaging.md#messagingapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this Messaging instance is associated with. | - -## Messaging.app - -The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `Messaging` instance is associated with. - -Signature: - -```typescript -app: FirebaseApp; -``` diff --git a/docs-devsite/messaging_sw.notificationpayload.md b/docs-devsite/messaging_sw.notificationpayload.md deleted file mode 100644 index c49ecfdf123..00000000000 --- a/docs-devsite/messaging_sw.notificationpayload.md +++ /dev/null @@ -1,68 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# NotificationPayload interface -Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) - -Signature: - -```typescript -export interface NotificationPayload -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [body](./messaging_sw.notificationpayload.md#notificationpayloadbody) | string | The notification's body text. | -| [icon](./messaging_sw.notificationpayload.md#notificationpayloadicon) | string | The URL to use for the notification's icon. If you don't send this key in the request, FCM displays the launcher icon specified in your app manifest. | -| [image](./messaging_sw.notificationpayload.md#notificationpayloadimage) | string | The URL of an image that is downloaded on the device and displayed in the notification. | -| [title](./messaging_sw.notificationpayload.md#notificationpayloadtitle) | string | The notification's title. | - -## NotificationPayload.body - -The notification's body text. - -Signature: - -```typescript -body?: string; -``` - -## NotificationPayload.icon - -The URL to use for the notification's icon. If you don't send this key in the request, FCM displays the launcher icon specified in your app manifest. - -Signature: - -```typescript -icon?: string; -``` - -## NotificationPayload.image - -The URL of an image that is downloaded on the device and displayed in the notification. - -Signature: - -```typescript -image?: string; -``` - -## NotificationPayload.title - -The notification's title. - -Signature: - -```typescript -title?: string; -``` diff --git a/docs-devsite/performance.firebaseperformance.md b/docs-devsite/performance.firebaseperformance.md deleted file mode 100644 index d8aea429952..00000000000 --- a/docs-devsite/performance.firebaseperformance.md +++ /dev/null @@ -1,57 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FirebasePerformance interface -The Firebase Performance Monitoring service interface. - -Signature: - -```typescript -export interface FirebasePerformance -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [app](./performance.firebaseperformance.md#firebaseperformanceapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this FirebasePerformance instance is associated with. | -| [dataCollectionEnabled](./performance.firebaseperformance.md#firebaseperformancedatacollectionenabled) | boolean | Controls the logging of custom traces. | -| [instrumentationEnabled](./performance.firebaseperformance.md#firebaseperformanceinstrumentationenabled) | boolean | Controls the logging of automatic traces and HTTP/S network monitoring. | - -## FirebasePerformance.app - -The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `FirebasePerformance` instance is associated with. - -Signature: - -```typescript -app: FirebaseApp; -``` - -## FirebasePerformance.dataCollectionEnabled - -Controls the logging of custom traces. - -Signature: - -```typescript -dataCollectionEnabled: boolean; -``` - -## FirebasePerformance.instrumentationEnabled - -Controls the logging of automatic traces and HTTP/S network monitoring. - -Signature: - -```typescript -instrumentationEnabled: boolean; -``` diff --git a/docs-devsite/performance.md b/docs-devsite/performance.md deleted file mode 100644 index 247002ed70a..00000000000 --- a/docs-devsite/performance.md +++ /dev/null @@ -1,94 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# performance package -Firebase Performance Monitoring - -## Functions - -| Function | Description | -| --- | --- | -| function(app...) | -| [getPerformance(app)](./performance.md#getperformance) | Returns a [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) instance for the given app. | -| [initializePerformance(app, settings)](./performance.md#initializeperformance) | Returns a [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) instance for the given app. Can only be called once. | -| function(performance...) | -| [trace(performance, name)](./performance.md#trace) | Returns a new PerformanceTrace instance. | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) | The Firebase Performance Monitoring service interface. | -| [PerformanceSettings](./performance.performancesettings.md#performancesettings_interface) | Defines configuration options for the Performance Monitoring SDK. | -| [PerformanceTrace](./performance.performancetrace.md#performancetrace_interface) | The interface representing a Trace. | - -## getPerformance() - -Returns a [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) instance for the given app. - -Signature: - -```typescript -export declare function getPerformance(app?: FirebaseApp): FirebasePerformance; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to use. | - -Returns: - -[FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) - -## initializePerformance() - -Returns a [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) instance for the given app. Can only be called once. - -Signature: - -```typescript -export declare function initializePerformance(app: FirebaseApp, settings?: PerformanceSettings): FirebasePerformance; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to use. | -| settings | [PerformanceSettings](./performance.performancesettings.md#performancesettings_interface) | Optional settings for the [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) instance. | - -Returns: - -[FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) - -## trace() - -Returns a new `PerformanceTrace` instance. - -Signature: - -```typescript -export declare function trace(performance: FirebasePerformance, name: string): PerformanceTrace; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| performance | [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) | The [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) instance to use. | -| name | string | The name of the trace. | - -Returns: - -[PerformanceTrace](./performance.performancetrace.md#performancetrace_interface) - diff --git a/docs-devsite/performance.performancesettings.md b/docs-devsite/performance.performancesettings.md deleted file mode 100644 index 9d85a96ce6a..00000000000 --- a/docs-devsite/performance.performancesettings.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# PerformanceSettings interface -Defines configuration options for the Performance Monitoring SDK. - -Signature: - -```typescript -export interface PerformanceSettings -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [dataCollectionEnabled](./performance.performancesettings.md#performancesettingsdatacollectionenabled) | boolean | Whether to collect custom events. | -| [instrumentationEnabled](./performance.performancesettings.md#performancesettingsinstrumentationenabled) | boolean | Whether to collect out of the box events. | - -## PerformanceSettings.dataCollectionEnabled - -Whether to collect custom events. - -Signature: - -```typescript -dataCollectionEnabled?: boolean; -``` - -## PerformanceSettings.instrumentationEnabled - -Whether to collect out of the box events. - -Signature: - -```typescript -instrumentationEnabled?: boolean; -``` diff --git a/docs-devsite/performance.performancetrace.md b/docs-devsite/performance.performancetrace.md deleted file mode 100644 index ffda20476da..00000000000 --- a/docs-devsite/performance.performancetrace.md +++ /dev/null @@ -1,228 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# PerformanceTrace interface -The interface representing a `Trace`. - -Signature: - -```typescript -export interface PerformanceTrace -``` - -## Methods - -| Method | Description | -| --- | --- | -| [getAttribute(attr)](./performance.performancetrace.md#performancetracegetattribute) | Retrieves the value which a custom attribute is set to. | -| [getAttributes()](./performance.performancetrace.md#performancetracegetattributes) | Returns a map of all custom attributes of a trace instance. | -| [getMetric(metricName)](./performance.performancetrace.md#performancetracegetmetric) | Returns the value of the custom metric by that name. If a custom metric with that name does not exist will return zero. | -| [incrementMetric(metricName, num)](./performance.performancetrace.md#performancetraceincrementmetric) | Adds to the value of a custom metric. If a custom metric with the provided name does not exist, it creates one with that name and the value equal to the given number. The value will be floored down to an integer. | -| [putAttribute(attr, value)](./performance.performancetrace.md#performancetraceputattribute) | Set a custom attribute of a trace to a certain value. | -| [putMetric(metricName, num)](./performance.performancetrace.md#performancetraceputmetric) | Sets the value of the specified custom metric to the given number regardless of whether a metric with that name already exists on the trace instance or not. The value will be floored down to an integer. | -| [record(startTime, duration, options)](./performance.performancetrace.md#performancetracerecord) | Records a trace from given parameters. This provides a direct way to use trace without a need to start/stop. This is useful for use cases in which the trace cannot directly be used (e.g. if the duration was captured before the Performance SDK was loaded). | -| [removeAttribute(attr)](./performance.performancetrace.md#performancetraceremoveattribute) | Removes the specified custom attribute from a trace instance. | -| [start()](./performance.performancetrace.md#performancetracestart) | Starts the timing for the trace instance. | -| [stop()](./performance.performancetrace.md#performancetracestop) | Stops the timing of the trace instance and logs the data of the instance. | - -## PerformanceTrace.getAttribute() - -Retrieves the value which a custom attribute is set to. - -Signature: - -```typescript -getAttribute(attr: string): string | undefined; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| attr | string | Name of the custom attribute. | - -Returns: - -string \| undefined - -## PerformanceTrace.getAttributes() - -Returns a map of all custom attributes of a trace instance. - -Signature: - -```typescript -getAttributes(): { - [key: string]: string; - }; -``` -Returns: - -{ \[key: string\]: string; } - -## PerformanceTrace.getMetric() - -Returns the value of the custom metric by that name. If a custom metric with that name does not exist will return zero. - -Signature: - -```typescript -getMetric(metricName: string): number; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| metricName | string | Name of the custom metric. | - -Returns: - -number - -## PerformanceTrace.incrementMetric() - -Adds to the value of a custom metric. If a custom metric with the provided name does not exist, it creates one with that name and the value equal to the given number. The value will be floored down to an integer. - -Signature: - -```typescript -incrementMetric(metricName: string, num?: number): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| metricName | string | The name of the custom metric. | -| num | number | The number to be added to the value of the custom metric. If not provided, it uses a default value of one. | - -Returns: - -void - -## PerformanceTrace.putAttribute() - -Set a custom attribute of a trace to a certain value. - -Signature: - -```typescript -putAttribute(attr: string, value: string): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| attr | string | Name of the custom attribute. | -| value | string | Value of the custom attribute. | - -Returns: - -void - -## PerformanceTrace.putMetric() - -Sets the value of the specified custom metric to the given number regardless of whether a metric with that name already exists on the trace instance or not. The value will be floored down to an integer. - -Signature: - -```typescript -putMetric(metricName: string, num: number): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| metricName | string | Name of the custom metric. | -| num | number | Value to of the custom metric. | - -Returns: - -void - -## PerformanceTrace.record() - -Records a trace from given parameters. This provides a direct way to use trace without a need to start/stop. This is useful for use cases in which the trace cannot directly be used (e.g. if the duration was captured before the Performance SDK was loaded). - -Signature: - -```typescript -record(startTime: number, duration: number, options?: { - metrics?: { - [key: string]: number; - }; - attributes?: { - [key: string]: string; - }; - }): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| startTime | number | trace start time since epoch in millisec. | -| duration | number | The duraction of the trace in millisec. | -| options | { metrics?: { \[key: string\]: number; }; attributes?: { \[key: string\]: string; }; } | An object which can optionally hold maps of custom metrics and custom attributes. | - -Returns: - -void - -## PerformanceTrace.removeAttribute() - -Removes the specified custom attribute from a trace instance. - -Signature: - -```typescript -removeAttribute(attr: string): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| attr | string | Name of the custom attribute. | - -Returns: - -void - -## PerformanceTrace.start() - -Starts the timing for the trace instance. - -Signature: - -```typescript -start(): void; -``` -Returns: - -void - -## PerformanceTrace.stop() - -Stops the timing of the trace instance and logs the data of the instance. - -Signature: - -```typescript -stop(): void; -``` -Returns: - -void - diff --git a/docs-devsite/remote-config.md b/docs-devsite/remote-config.md deleted file mode 100644 index 5011c3b12b9..00000000000 --- a/docs-devsite/remote-config.md +++ /dev/null @@ -1,345 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# remote-config package -Firebase Remote Config - -## Functions - -| Function | Description | -| --- | --- | -| function(app...) | -| [getRemoteConfig(app)](./remote-config.md#getremoteconfig) | | -| function(remoteConfig...) | -| [activate(remoteConfig)](./remote-config.md#activate) | Makes the last fetched config available to the getters. | -| [ensureInitialized(remoteConfig)](./remote-config.md#ensureinitialized) | Ensures the last activated config are available to the getters. | -| [fetchAndActivate(remoteConfig)](./remote-config.md#fetchandactivate) | Performs fetch and activate operations, as a convenience. | -| [fetchConfig(remoteConfig)](./remote-config.md#fetchconfig) | Fetches and caches configuration from the Remote Config service. | -| [getAll(remoteConfig)](./remote-config.md#getall) | Gets all config. | -| [getBoolean(remoteConfig, key)](./remote-config.md#getboolean) | Gets the value for the given key as a boolean.Convenience method for calling remoteConfig.getValue(key).asBoolean(). | -| [getNumber(remoteConfig, key)](./remote-config.md#getnumber) | Gets the value for the given key as a number.Convenience method for calling remoteConfig.getValue(key).asNumber(). | -| [getString(remoteConfig, key)](./remote-config.md#getstring) | Gets the value for the given key as a string. Convenience method for calling remoteConfig.getValue(key).asString(). | -| [getValue(remoteConfig, key)](./remote-config.md#getvalue) | Gets the [Value](./remote-config.value.md#value_interface) for the given key. | -| [setLogLevel(remoteConfig, logLevel)](./remote-config.md#setloglevel) | Defines the log level to use. | -| function() | -| [isSupported()](./remote-config.md#issupported) | This method provides two different checks:1. Check if IndexedDB exists in the browser environment. 2. Check if the current browser context allows IndexedDB open() calls. | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The Firebase Remote Config service interface. | -| [RemoteConfigSettings](./remote-config.remoteconfigsettings.md#remoteconfigsettings_interface) | Defines configuration options for the Remote Config SDK. | -| [Value](./remote-config.value.md#value_interface) | Wraps a value with metadata and type-safe getters. | - -## Type Aliases - -| Type Alias | Description | -| --- | --- | -| [FetchStatus](./remote-config.md#fetchstatus) | Summarizes the outcome of the last attempt to fetch config from the Firebase Remote Config server.
  • "no-fetch-yet" indicates the [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance has not yet attempted to fetch config, or that SDK initialization is incomplete.
  • "success" indicates the last attempt succeeded.
  • "failure" indicates the last attempt failed.
  • "throttle" indicates the last attempt was rate-limited.
| -| [LogLevel](./remote-config.md#loglevel) | Defines levels of Remote Config logging. | -| [ValueSource](./remote-config.md#valuesource) | Indicates the source of a value.
  • "static" indicates the value was defined by a static constant.
  • "default" indicates the value was defined by default config.
  • "remote" indicates the value was defined by fetched config.
| - -## getRemoteConfig() - -Signature: - -```typescript -export declare function getRemoteConfig(app?: FirebaseApp): RemoteConfig; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. | - -Returns: - -[RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) - -A [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. - -## activate() - -Makes the last fetched config available to the getters. - -Signature: - -```typescript -export declare function activate(remoteConfig: RemoteConfig): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | - -Returns: - -Promise<boolean> - -A `Promise` which resolves to true if the current call activated the fetched configs. If the fetched configs were already activated, the `Promise` will resolve to false. - -## ensureInitialized() - -Ensures the last activated config are available to the getters. - -Signature: - -```typescript -export declare function ensureInitialized(remoteConfig: RemoteConfig): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | - -Returns: - -Promise<void> - -A `Promise` that resolves when the last activated config is available to the getters. - -## fetchAndActivate() - -Performs fetch and activate operations, as a convenience. - -Signature: - -```typescript -export declare function fetchAndActivate(remoteConfig: RemoteConfig): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | - -Returns: - -Promise<boolean> - -A `Promise` which resolves to true if the current call activated the fetched configs. If the fetched configs were already activated, the `Promise` will resolve to false. - -## fetchConfig() - -Fetches and caches configuration from the Remote Config service. - -Signature: - -```typescript -export declare function fetchConfig(remoteConfig: RemoteConfig): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | - -Returns: - -Promise<void> - -## getAll() - -Gets all config. - -Signature: - -```typescript -export declare function getAll(remoteConfig: RemoteConfig): Record; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | - -Returns: - -Record<string, [Value](./remote-config.value.md#value_interface)> - -All config. - -## getBoolean() - -Gets the value for the given key as a boolean. - -Convenience method for calling remoteConfig.getValue(key).asBoolean(). - -Signature: - -```typescript -export declare function getBoolean(remoteConfig: RemoteConfig, key: string): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | -| key | string | The name of the parameter. | - -Returns: - -boolean - -The value for the given key as a boolean. - -## getNumber() - -Gets the value for the given key as a number. - -Convenience method for calling remoteConfig.getValue(key).asNumber(). - -Signature: - -```typescript -export declare function getNumber(remoteConfig: RemoteConfig, key: string): number; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | -| key | string | The name of the parameter. | - -Returns: - -number - -The value for the given key as a number. - -## getString() - -Gets the value for the given key as a string. Convenience method for calling remoteConfig.getValue(key).asString(). - -Signature: - -```typescript -export declare function getString(remoteConfig: RemoteConfig, key: string): string; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | -| key | string | The name of the parameter. | - -Returns: - -string - -The value for the given key as a string. - -## getValue() - -Gets the [Value](./remote-config.value.md#value_interface) for the given key. - -Signature: - -```typescript -export declare function getValue(remoteConfig: RemoteConfig, key: string): Value; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | -| key | string | The name of the parameter. | - -Returns: - -[Value](./remote-config.value.md#value_interface) - -The value for the given key. - -## setLogLevel() - -Defines the log level to use. - -Signature: - -```typescript -export declare function setLogLevel(remoteConfig: RemoteConfig, logLevel: RemoteConfigLogLevel): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | -| logLevel | [RemoteConfigLogLevel](./remote-config.md#loglevel) | The log level to set. | - -Returns: - -void - -## isSupported() - -This method provides two different checks: - -1. Check if IndexedDB exists in the browser environment. 2. Check if the current browser context allows IndexedDB `open()` calls. - -Signature: - -```typescript -export declare function isSupported(): Promise; -``` -Returns: - -Promise<boolean> - -A `Promise` which resolves to true if a [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance can be initialized in this environment, or false if it cannot. - -## FetchStatus - -Summarizes the outcome of the last attempt to fetch config from the Firebase Remote Config server. - -
  • "no-fetch-yet" indicates the [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance has not yet attempted to fetch config, or that SDK initialization is incomplete.
  • "success" indicates the last attempt succeeded.
  • "failure" indicates the last attempt failed.
  • "throttle" indicates the last attempt was rate-limited.
- -Signature: - -```typescript -export declare type FetchStatus = 'no-fetch-yet' | 'success' | 'failure' | 'throttle'; -``` - -## LogLevel - -Defines levels of Remote Config logging. - -Signature: - -```typescript -export declare type LogLevel = 'debug' | 'error' | 'silent'; -``` - -## ValueSource - -Indicates the source of a value. - -
  • "static" indicates the value was defined by a static constant.
  • "default" indicates the value was defined by default config.
  • "remote" indicates the value was defined by fetched config.
- -Signature: - -```typescript -export declare type ValueSource = 'static' | 'default' | 'remote'; -``` diff --git a/docs-devsite/remote-config.remoteconfig.md b/docs-devsite/remote-config.remoteconfig.md deleted file mode 100644 index 3f4f0688b13..00000000000 --- a/docs-devsite/remote-config.remoteconfig.md +++ /dev/null @@ -1,81 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# RemoteConfig interface -The Firebase Remote Config service interface. - -Signature: - -```typescript -export interface RemoteConfig -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [app](./remote-config.remoteconfig.md#remoteconfigapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this RemoteConfig instance is associated with. | -| [defaultConfig](./remote-config.remoteconfig.md#remoteconfigdefaultconfig) | { \[key: string\]: string \| number \| boolean; } | Object containing default values for configs. | -| [fetchTimeMillis](./remote-config.remoteconfig.md#remoteconfigfetchtimemillis) | number | The Unix timestamp in milliseconds of the last successful fetch, or negative one if the [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance either hasn't fetched or initialization is incomplete. | -| [lastFetchStatus](./remote-config.remoteconfig.md#remoteconfiglastfetchstatus) | [FetchStatus](./remote-config.md#fetchstatus) | The status of the last fetch attempt. | -| [settings](./remote-config.remoteconfig.md#remoteconfigsettings) | [RemoteConfigSettings](./remote-config.remoteconfigsettings.md#remoteconfigsettings_interface) | Defines configuration for the Remote Config SDK. | - -## RemoteConfig.app - -The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `RemoteConfig` instance is associated with. - -Signature: - -```typescript -app: FirebaseApp; -``` - -## RemoteConfig.defaultConfig - -Object containing default values for configs. - -Signature: - -```typescript -defaultConfig: { - [key: string]: string | number | boolean; - }; -``` - -## RemoteConfig.fetchTimeMillis - -The Unix timestamp in milliseconds of the last successful fetch, or negative one if the [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance either hasn't fetched or initialization is incomplete. - -Signature: - -```typescript -fetchTimeMillis: number; -``` - -## RemoteConfig.lastFetchStatus - -The status of the last fetch attempt. - -Signature: - -```typescript -lastFetchStatus: FetchStatus; -``` - -## RemoteConfig.settings - -Defines configuration for the Remote Config SDK. - -Signature: - -```typescript -settings: RemoteConfigSettings; -``` diff --git a/docs-devsite/remote-config.remoteconfigsettings.md b/docs-devsite/remote-config.remoteconfigsettings.md deleted file mode 100644 index 58e505ad863..00000000000 --- a/docs-devsite/remote-config.remoteconfigsettings.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# RemoteConfigSettings interface -Defines configuration options for the Remote Config SDK. - -Signature: - -```typescript -export interface RemoteConfigSettings -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [fetchTimeoutMillis](./remote-config.remoteconfigsettings.md#remoteconfigsettingsfetchtimeoutmillis) | number | Defines the maximum amount of milliseconds to wait for a response when fetching configuration from the Remote Config server. Defaults to 60000 (One minute). | -| [minimumFetchIntervalMillis](./remote-config.remoteconfigsettings.md#remoteconfigsettingsminimumfetchintervalmillis) | number | Defines the maximum age in milliseconds of an entry in the config cache before it is considered stale. Defaults to 43200000 (Twelve hours). | - -## RemoteConfigSettings.fetchTimeoutMillis - -Defines the maximum amount of milliseconds to wait for a response when fetching configuration from the Remote Config server. Defaults to 60000 (One minute). - -Signature: - -```typescript -fetchTimeoutMillis: number; -``` - -## RemoteConfigSettings.minimumFetchIntervalMillis - -Defines the maximum age in milliseconds of an entry in the config cache before it is considered stale. Defaults to 43200000 (Twelve hours). - -Signature: - -```typescript -minimumFetchIntervalMillis: number; -``` diff --git a/docs-devsite/remote-config.value.md b/docs-devsite/remote-config.value.md deleted file mode 100644 index 36fb492d524..00000000000 --- a/docs-devsite/remote-config.value.md +++ /dev/null @@ -1,83 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# Value interface -Wraps a value with metadata and type-safe getters. - -Signature: - -```typescript -export interface Value -``` - -## Methods - -| Method | Description | -| --- | --- | -| [asBoolean()](./remote-config.value.md#valueasboolean) | Gets the value as a boolean.The following values (case insensitive) are interpreted as true: "1", "true", "t", "yes", "y", "on". Other values are interpreted as false. | -| [asNumber()](./remote-config.value.md#valueasnumber) | Gets the value as a number. Comparable to calling Number(value) \|\| 0. | -| [asString()](./remote-config.value.md#valueasstring) | Gets the value as a string. | -| [getSource()](./remote-config.value.md#valuegetsource) | Gets the [ValueSource](./remote-config.md#valuesource) for the given key. | - -## Value.asBoolean() - -Gets the value as a boolean. - -The following values (case insensitive) are interpreted as true: "1", "true", "t", "yes", "y", "on". Other values are interpreted as false. - -Signature: - -```typescript -asBoolean(): boolean; -``` -Returns: - -boolean - -## Value.asNumber() - -Gets the value as a number. Comparable to calling Number(value) \|\| 0. - -Signature: - -```typescript -asNumber(): number; -``` -Returns: - -number - -## Value.asString() - -Gets the value as a string. - -Signature: - -```typescript -asString(): string; -``` -Returns: - -string - -## Value.getSource() - -Gets the [ValueSource](./remote-config.md#valuesource) for the given key. - -Signature: - -```typescript -getSource(): ValueSource; -``` -Returns: - -[ValueSource](./remote-config.md#valuesource) - diff --git a/docs-devsite/storage.firebasestorage.md b/docs-devsite/storage.firebasestorage.md deleted file mode 100644 index a44df8bfc3d..00000000000 --- a/docs-devsite/storage.firebasestorage.md +++ /dev/null @@ -1,58 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FirebaseStorage interface -A Firebase Storage instance. - -Signature: - -```typescript -export interface FirebaseStorage extends _FirebaseService -``` -Extends: \_FirebaseService - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [app](./storage.firebasestorage.md#firebasestorageapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this FirebaseStorage instance. | -| [maxOperationRetryTime](./storage.firebasestorage.md#firebasestoragemaxoperationretrytime) | number | The maximum time to retry operations other than uploads or downloads in milliseconds. | -| [maxUploadRetryTime](./storage.firebasestorage.md#firebasestoragemaxuploadretrytime) | number | The maximum time to retry uploads in milliseconds. | - -## FirebaseStorage.app - -The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this `FirebaseStorage` instance. - -Signature: - -```typescript -readonly app: FirebaseApp; -``` - -## FirebaseStorage.maxOperationRetryTime - -The maximum time to retry operations other than uploads or downloads in milliseconds. - -Signature: - -```typescript -maxOperationRetryTime: number; -``` - -## FirebaseStorage.maxUploadRetryTime - -The maximum time to retry uploads in milliseconds. - -Signature: - -```typescript -maxUploadRetryTime: number; -``` diff --git a/docs-devsite/storage.fullmetadata.md b/docs-devsite/storage.fullmetadata.md deleted file mode 100644 index ca8d66e08d5..00000000000 --- a/docs-devsite/storage.fullmetadata.md +++ /dev/null @@ -1,135 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# FullMetadata interface -The full set of object metadata, including read-only properties. - -Signature: - -```typescript -export interface FullMetadata extends UploadMetadata -``` -Extends: [UploadMetadata](./storage.uploadmetadata.md#uploadmetadata_interface) - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [bucket](./storage.fullmetadata.md#fullmetadatabucket) | string | The bucket this object is contained in. | -| [downloadTokens](./storage.fullmetadata.md#fullmetadatadownloadtokens) | string\[\] \| undefined | Tokens to allow access to the downloatd URL. | -| [fullPath](./storage.fullmetadata.md#fullmetadatafullpath) | string | The full path of this object. | -| [generation](./storage.fullmetadata.md#fullmetadatageneration) | string | The object's generation. [https://cloud.google.com/storage/docs/metadata\#generation-number](https://cloud.google.com/storage/docs/metadata#generation-number) | -| [metageneration](./storage.fullmetadata.md#fullmetadatametageneration) | string | The object's metageneration. [https://cloud.google.com/storage/docs/metadata\#generation-number](https://cloud.google.com/storage/docs/metadata#generation-number) | -| [name](./storage.fullmetadata.md#fullmetadataname) | string | The short name of this object, which is the last component of the full path. For example, if fullPath is 'full/path/image.png', name is 'image.png'. | -| [ref](./storage.fullmetadata.md#fullmetadataref) | [StorageReference](./storage.storagereference.md#storagereference_interface) \| undefined | StorageReference associated with this upload. | -| [size](./storage.fullmetadata.md#fullmetadatasize) | number | The size of this object, in bytes. | -| [timeCreated](./storage.fullmetadata.md#fullmetadatatimecreated) | string | A date string representing when this object was created. | -| [updated](./storage.fullmetadata.md#fullmetadataupdated) | string | A date string representing when this object was last updated. | - -## FullMetadata.bucket - -The bucket this object is contained in. - -Signature: - -```typescript -bucket: string; -``` - -## FullMetadata.downloadTokens - -Tokens to allow access to the downloatd URL. - -Signature: - -```typescript -downloadTokens: string[] | undefined; -``` - -## FullMetadata.fullPath - -The full path of this object. - -Signature: - -```typescript -fullPath: string; -``` - -## FullMetadata.generation - -The object's generation. [https://cloud.google.com/storage/docs/metadata\#generation-number](https://cloud.google.com/storage/docs/metadata#generation-number) - -Signature: - -```typescript -generation: string; -``` - -## FullMetadata.metageneration - -The object's metageneration. [https://cloud.google.com/storage/docs/metadata\#generation-number](https://cloud.google.com/storage/docs/metadata#generation-number) - -Signature: - -```typescript -metageneration: string; -``` - -## FullMetadata.name - -The short name of this object, which is the last component of the full path. For example, if fullPath is 'full/path/image.png', name is 'image.png'. - -Signature: - -```typescript -name: string; -``` - -## FullMetadata.ref - -`StorageReference` associated with this upload. - -Signature: - -```typescript -ref?: StorageReference | undefined; -``` - -## FullMetadata.size - -The size of this object, in bytes. - -Signature: - -```typescript -size: number; -``` - -## FullMetadata.timeCreated - -A date string representing when this object was created. - -Signature: - -```typescript -timeCreated: string; -``` - -## FullMetadata.updated - -A date string representing when this object was last updated. - -Signature: - -```typescript -updated: string; -``` diff --git a/docs-devsite/storage.listoptions.md b/docs-devsite/storage.listoptions.md deleted file mode 100644 index 3f2e92bc639..00000000000 --- a/docs-devsite/storage.listoptions.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ListOptions interface -The options `list()` accepts. - -Signature: - -```typescript -export interface ListOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [maxResults](./storage.listoptions.md#listoptionsmaxresults) | number \| null | If set, limits the total number of prefixes and items to return. The default and maximum maxResults is 1000. | -| [pageToken](./storage.listoptions.md#listoptionspagetoken) | string \| null | The nextPageToken from a previous call to list(). If provided, listing is resumed from the previous position. | - -## ListOptions.maxResults - -If set, limits the total number of `prefixes` and `items` to return. The default and maximum maxResults is 1000. - -Signature: - -```typescript -maxResults?: number | null; -``` - -## ListOptions.pageToken - -The `nextPageToken` from a previous call to `list()`. If provided, listing is resumed from the previous position. - -Signature: - -```typescript -pageToken?: string | null; -``` diff --git a/docs-devsite/storage.listresult.md b/docs-devsite/storage.listresult.md deleted file mode 100644 index b53a61d92db..00000000000 --- a/docs-devsite/storage.listresult.md +++ /dev/null @@ -1,59 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# ListResult interface -Result returned by list(). - -Signature: - -```typescript -export interface ListResult -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [items](./storage.listresult.md#listresultitems) | [StorageReference](./storage.storagereference.md#storagereference_interface)\[\] | Objects in this directory. You can call getMetadata() and getDownloadUrl() on them. | -| [nextPageToken](./storage.listresult.md#listresultnextpagetoken) | string | If set, there might be more results for this list. Use this token to resume the list. | -| [prefixes](./storage.listresult.md#listresultprefixes) | [StorageReference](./storage.storagereference.md#storagereference_interface)\[\] | References to prefixes (sub-folders). You can call list() on them to get its contents.Folders are implicit based on '/' in the object paths. For example, if a bucket has two objects '/a/b/1' and '/a/b/2', list('/a') will return '/a/b' as a prefix. | - -## ListResult.items - -Objects in this directory. You can call getMetadata() and getDownloadUrl() on them. - -Signature: - -```typescript -items: StorageReference[]; -``` - -## ListResult.nextPageToken - -If set, there might be more results for this list. Use this token to resume the list. - -Signature: - -```typescript -nextPageToken?: string; -``` - -## ListResult.prefixes - -References to prefixes (sub-folders). You can call list() on them to get its contents. - -Folders are implicit based on '/' in the object paths. For example, if a bucket has two objects '/a/b/1' and '/a/b/2', list('/a') will return '/a/b' as a prefix. - -Signature: - -```typescript -prefixes: StorageReference[]; -``` diff --git a/docs-devsite/storage.md b/docs-devsite/storage.md deleted file mode 100644 index 0aab0c6a35d..00000000000 --- a/docs-devsite/storage.md +++ /dev/null @@ -1,550 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# storage package -Cloud Storage for Firebase - -## Functions - -| Function | Description | -| --- | --- | -| function(app...) | -| [getStorage(app, bucketUrl)](./storage.md#getstorage) | Gets a [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance for the given Firebase app. | -| function(storage...) | -| [connectStorageEmulator(storage, host, port, options)](./storage.md#connectstorageemulator) | Modify this [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance to communicate with the Cloud Storage emulator. | -| [ref(storage, url)](./storage.md#ref) | Returns a [StorageReference](./storage.storagereference.md#storagereference_interface) for the given url. | -| function(ref...) | -| [deleteObject(ref)](./storage.md#deleteobject) | Deletes the object at this location. | -| [getBlob(ref, maxDownloadSizeBytes)](./storage.md#getblob) | Downloads the data at the object's location. Returns an error if the object is not found.To use this functionality, you have to whitelist your app's origin in your Cloud Storage bucket. See also https://cloud.google.com/storage/docs/configuring-corsThis API is not available in Node. | -| [getBytes(ref, maxDownloadSizeBytes)](./storage.md#getbytes) | Downloads the data at the object's location. Returns an error if the object is not found.To use this functionality, you have to whitelist your app's origin in your Cloud Storage bucket. See also https://cloud.google.com/storage/docs/configuring-cors | -| [getDownloadURL(ref)](./storage.md#getdownloadurl) | Returns the download URL for the given [StorageReference](./storage.storagereference.md#storagereference_interface). | -| [getMetadata(ref)](./storage.md#getmetadata) | A Promise that resolves with the metadata for this object. If this object doesn't exist or metadata cannot be retreived, the promise is rejected. | -| [getStream(ref, maxDownloadSizeBytes)](./storage.md#getstream) | Downloads the data at the object's location. Raises an error event if the object is not found.This API is only available in Node. | -| [list(ref, options)](./storage.md#list) | List items (files) and prefixes (folders) under this storage reference.List API is only available for Firebase Rules Version 2.GCS is a key-blob store. Firebase Storage imposes the semantic of '/' delimited folder structure. Refer to GCS's List API if you want to learn more.To adhere to Firebase Rules's Semantics, Firebase Storage does not support objects whose paths end with "/" or contain two consecutive "/"s. Firebase Storage List API will filter these unsupported objects. list() may fail if there are too many unsupported objects in the bucket. | -| [listAll(ref)](./storage.md#listall) | List all items (files) and prefixes (folders) under this storage reference.This is a helper method for calling list() repeatedly until there are no more results. The default pagination size is 1000.Note: The results may not be consistent if objects are changed while this operation is running.Warning: listAll may potentially consume too many resources if there are too many results. | -| [updateMetadata(ref, metadata)](./storage.md#updatemetadata) | Updates the metadata for this object. | -| [uploadBytes(ref, data, metadata)](./storage.md#uploadbytes) | Uploads data to this object's location. The upload is not resumable. | -| [uploadBytesResumable(ref, data, metadata)](./storage.md#uploadbytesresumable) | Uploads data to this object's location. The upload can be paused and resumed, and exposes progress updates. | -| [uploadString(ref, value, format, metadata)](./storage.md#uploadstring) | Uploads a string to this object's location. The upload is not resumable. | -| function(storageOrRef...) | -| [ref(storageOrRef, path)](./storage.md#ref) | Returns a [StorageReference](./storage.storagereference.md#storagereference_interface) for the given path in the default bucket. | - -## Classes - -| Class | Description | -| --- | --- | -| [StorageError](./storage.storageerror.md#storageerror_class) | An error returned by the Firebase Storage SDK. | - -## Enumerations - -| Enumeration | Description | -| --- | --- | -| [StorageErrorCode](./storage.md#storageerrorcode) | Error codes that can be attached to StorageError objects. | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) | A Firebase Storage instance. | -| [FullMetadata](./storage.fullmetadata.md#fullmetadata_interface) | The full set of object metadata, including read-only properties. | -| [ListOptions](./storage.listoptions.md#listoptions_interface) | The options list() accepts. | -| [ListResult](./storage.listresult.md#listresult_interface) | Result returned by list(). | -| [SettableMetadata](./storage.settablemetadata.md#settablemetadata_interface) | Object metadata that can be set at any time. | -| [StorageObserver](./storage.storageobserver.md#storageobserver_interface) | A stream observer for Firebase Storage. | -| [StorageReference](./storage.storagereference.md#storagereference_interface) | Represents a reference to a Google Cloud Storage object. Developers can upload, download, and delete objects, as well as get/set object metadata. | -| [UploadMetadata](./storage.uploadmetadata.md#uploadmetadata_interface) | Object metadata that can be set at upload. | -| [UploadResult](./storage.uploadresult.md#uploadresult_interface) | Result returned from a non-resumable upload. | -| [UploadTask](./storage.uploadtask.md#uploadtask_interface) | Represents the process of uploading an object. Allows you to monitor and manage the upload. | -| [UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface) | Holds data about the current state of the upload task. | - -## Variables - -| Variable | Description | -| --- | --- | -| [StringFormat](./storage.md#stringformat) | An enumeration of the possible string formats for upload. | - -## Type Aliases - -| Type Alias | Description | -| --- | --- | -| [StringFormat](./storage.md#stringformat) | An enumeration of the possible string formats for upload. | -| [TaskEvent](./storage.md#taskevent) | An event that is triggered on a task. | -| [TaskState](./storage.md#taskstate) | Represents the current state of a running upload. | - -## getStorage() - -Gets a [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance for the given Firebase app. - -Signature: - -```typescript -export declare function getStorage(app?: FirebaseApp, bucketUrl?: string): FirebaseStorage; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | Firebase app to get [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance for. | -| bucketUrl | string | The gs:// url to your Firebase Storage Bucket. If not passed, uses the app's default Storage Bucket. | - -Returns: - -[FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) - -A [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance. - -## connectStorageEmulator() - -Modify this [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance to communicate with the Cloud Storage emulator. - -Signature: - -```typescript -export declare function connectStorageEmulator(storage: FirebaseStorage, host: string, port: number, options?: { - mockUserToken?: EmulatorMockTokenOptions | string; -}): void; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| storage | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) | The [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance | -| host | string | The emulator host (ex: localhost) | -| port | number | The emulator port (ex: 5001) | -| options | { mockUserToken?: [EmulatorMockTokenOptions](./util.md#emulatormocktokenoptions) \| string; } | Emulator options. options.mockUserToken is the mock auth token to use for unit testing Security Rules. | - -Returns: - -void - -## ref() - -Returns a [StorageReference](./storage.storagereference.md#storagereference_interface) for the given url. - -Signature: - -```typescript -export declare function ref(storage: FirebaseStorage, url?: string): StorageReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| storage | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance. | -| url | string | URL. If empty, returns root reference. | - -Returns: - -[StorageReference](./storage.storagereference.md#storagereference_interface) - -## deleteObject() - -Deletes the object at this location. - -Signature: - -```typescript -export declare function deleteObject(ref: StorageReference): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) for object to delete. | - -Returns: - -Promise<void> - -A `Promise` that resolves if the deletion succeeds. - -## getBlob() - -Downloads the data at the object's location. Returns an error if the object is not found. - -To use this functionality, you have to whitelist your app's origin in your Cloud Storage bucket. See also https://cloud.google.com/storage/docs/configuring-cors - -This API is not available in Node. - -Signature: - -```typescript -export declare function getBlob(ref: StorageReference, maxDownloadSizeBytes?: number): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | StorageReference where data should be downloaded. | -| maxDownloadSizeBytes | number | If set, the maximum allowed size in bytes to retrieve. | - -Returns: - -Promise<Blob> - -A Promise that resolves with a Blob containing the object's bytes - -## getBytes() - -Downloads the data at the object's location. Returns an error if the object is not found. - -To use this functionality, you have to whitelist your app's origin in your Cloud Storage bucket. See also https://cloud.google.com/storage/docs/configuring-cors - -Signature: - -```typescript -export declare function getBytes(ref: StorageReference, maxDownloadSizeBytes?: number): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | StorageReference where data should be downloaded. | -| maxDownloadSizeBytes | number | If set, the maximum allowed size in bytes to retrieve. | - -Returns: - -Promise<ArrayBuffer> - -A Promise containing the object's bytes - -## getDownloadURL() - -Returns the download URL for the given [StorageReference](./storage.storagereference.md#storagereference_interface). - -Signature: - -```typescript -export declare function getDownloadURL(ref: StorageReference): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) to get the download URL for. | - -Returns: - -Promise<string> - -A `Promise` that resolves with the download URL for this object. - -## getMetadata() - -A `Promise` that resolves with the metadata for this object. If this object doesn't exist or metadata cannot be retreived, the promise is rejected. - -Signature: - -```typescript -export declare function getMetadata(ref: StorageReference): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) to get metadata from. | - -Returns: - -Promise<[FullMetadata](./storage.fullmetadata.md#fullmetadata_interface)> - -## getStream() - -Downloads the data at the object's location. Raises an error event if the object is not found. - -This API is only available in Node. - -Signature: - -```typescript -export declare function getStream(ref: StorageReference, maxDownloadSizeBytes?: number): NodeJS.ReadableStream; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | StorageReference where data should be downloaded. | -| maxDownloadSizeBytes | number | If set, the maximum allowed size in bytes to retrieve. | - -Returns: - -NodeJS.ReadableStream - -A stream with the object's data as bytes - -## list() - -List items (files) and prefixes (folders) under this storage reference. - -List API is only available for Firebase Rules Version 2. - -GCS is a key-blob store. Firebase Storage imposes the semantic of '/' delimited folder structure. Refer to GCS's List API if you want to learn more. - -To adhere to Firebase Rules's Semantics, Firebase Storage does not support objects whose paths end with "/" or contain two consecutive "/"s. Firebase Storage List API will filter these unsupported objects. list() may fail if there are too many unsupported objects in the bucket. - -Signature: - -```typescript -export declare function list(ref: StorageReference, options?: ListOptions): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) to get list from. | -| options | [ListOptions](./storage.listoptions.md#listoptions_interface) | See [ListOptions](./storage.listoptions.md#listoptions_interface) for details. | - -Returns: - -Promise<[ListResult](./storage.listresult.md#listresult_interface)> - -A `Promise` that resolves with the items and prefixes. `prefixes` contains references to sub-folders and `items` contains references to objects in this folder. `nextPageToken` can be used to get the rest of the results. - -## listAll() - -List all items (files) and prefixes (folders) under this storage reference. - -This is a helper method for calling list() repeatedly until there are no more results. The default pagination size is 1000. - -Note: The results may not be consistent if objects are changed while this operation is running. - -Warning: `listAll` may potentially consume too many resources if there are too many results. - -Signature: - -```typescript -export declare function listAll(ref: StorageReference): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) to get list from. | - -Returns: - -Promise<[ListResult](./storage.listresult.md#listresult_interface)> - -A `Promise` that resolves with all the items and prefixes under the current storage reference. `prefixes` contains references to sub-directories and `items` contains references to objects in this folder. `nextPageToken` is never returned. - -## updateMetadata() - -Updates the metadata for this object. - -Signature: - -```typescript -export declare function updateMetadata(ref: StorageReference, metadata: SettableMetadata): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) to update metadata for. | -| metadata | [SettableMetadata](./storage.settablemetadata.md#settablemetadata_interface) | The new metadata for the object. Only values that have been explicitly set will be changed. Explicitly setting a value to null will remove the metadata. | - -Returns: - -Promise<[FullMetadata](./storage.fullmetadata.md#fullmetadata_interface)> - -A `Promise` that resolves with the new metadata for this object. - -## uploadBytes() - -Uploads data to this object's location. The upload is not resumable. - -Signature: - -```typescript -export declare function uploadBytes(ref: StorageReference, data: Blob | Uint8Array | ArrayBuffer, metadata?: UploadMetadata): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) where data should be uploaded. | -| data | Blob \| Uint8Array \| ArrayBuffer | The data to upload. | -| metadata | [UploadMetadata](./storage.uploadmetadata.md#uploadmetadata_interface) | Metadata for the data to upload. | - -Returns: - -Promise<[UploadResult](./storage.uploadresult.md#uploadresult_interface)> - -A Promise containing an UploadResult - -## uploadBytesResumable() - -Uploads data to this object's location. The upload can be paused and resumed, and exposes progress updates. - -Signature: - -```typescript -export declare function uploadBytesResumable(ref: StorageReference, data: Blob | Uint8Array | ArrayBuffer, metadata?: UploadMetadata): UploadTask; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) where data should be uploaded. | -| data | Blob \| Uint8Array \| ArrayBuffer | The data to upload. | -| metadata | [UploadMetadata](./storage.uploadmetadata.md#uploadmetadata_interface) | Metadata for the data to upload. | - -Returns: - -[UploadTask](./storage.uploadtask.md#uploadtask_interface) - -An UploadTask - -## uploadString() - -Uploads a string to this object's location. The upload is not resumable. - -Signature: - -```typescript -export declare function uploadString(ref: StorageReference, value: string, format?: StringFormat, metadata?: UploadMetadata): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) where string should be uploaded. | -| value | string | The string to upload. | -| format | [StringFormat](./storage.md#stringformat) | The format of the string to upload. | -| metadata | [UploadMetadata](./storage.uploadmetadata.md#uploadmetadata_interface) | Metadata for the string to upload. | - -Returns: - -Promise<[UploadResult](./storage.uploadresult.md#uploadresult_interface)> - -A Promise containing an UploadResult - -## ref() - -Returns a [StorageReference](./storage.storagereference.md#storagereference_interface) for the given path in the default bucket. - -Signature: - -```typescript -export declare function ref(storageOrRef: FirebaseStorage | StorageReference, path?: string): StorageReference; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| storageOrRef | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) \| [StorageReference](./storage.storagereference.md#storagereference_interface) | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) or [StorageReference](./storage.storagereference.md#storagereference_interface). | -| path | string | | - -Returns: - -[StorageReference](./storage.storagereference.md#storagereference_interface) - -## StringFormat - -An enumeration of the possible string formats for upload. - -Signature: - -```typescript -StringFormat: { - readonly RAW: "raw"; - readonly BASE64: "base64"; - readonly BASE64URL: "base64url"; - readonly DATA_URL: "data_url"; -} -``` - -## StringFormat - -An enumeration of the possible string formats for upload. - -Signature: - -```typescript -export declare type StringFormat = typeof StringFormat[keyof typeof StringFormat]; -``` - -## TaskEvent - -An event that is triggered on a task. - -Signature: - -```typescript -export declare type TaskEvent = 'state_changed'; -``` - -## TaskState - -Represents the current state of a running upload. - -Signature: - -```typescript -export declare type TaskState = 'running' | 'paused' | 'success' | 'canceled' | 'error'; -``` - -## StorageErrorCode - -Error codes that can be attached to `StorageError` objects. - -Signature: - -```typescript -export declare enum StorageErrorCode -``` - -## Enumeration Members - -| Member | Value | Description | -| --- | --- | --- | -| APP\_DELETED | "app-deleted" | | -| BUCKET\_NOT\_FOUND | "bucket-not-found" | | -| CANCELED | "canceled" | | -| CANNOT\_SLICE\_BLOB | "cannot-slice-blob" | | -| INTERNAL\_ERROR | "internal-error" | | -| INVALID\_ARGUMENT | "invalid-argument" | | -| INVALID\_ARGUMENT\_COUNT | "invalid-argument-count" | | -| INVALID\_CHECKSUM | "invalid-checksum" | | -| INVALID\_DEFAULT\_BUCKET | "invalid-default-bucket" | | -| INVALID\_EVENT\_NAME | "invalid-event-name" | | -| INVALID\_FORMAT | "invalid-format" | | -| INVALID\_ROOT\_OPERATION | "invalid-root-operation" | | -| INVALID\_URL | "invalid-url" | | -| NO\_DEFAULT\_BUCKET | "no-default-bucket" | | -| NO\_DOWNLOAD\_URL | "no-download-url" | | -| OBJECT\_NOT\_FOUND | "object-not-found" | | -| PROJECT\_NOT\_FOUND | "project-not-found" | | -| QUOTA\_EXCEEDED | "quota-exceeded" | | -| RETRY\_LIMIT\_EXCEEDED | "retry-limit-exceeded" | | -| SERVER\_FILE\_WRONG\_SIZE | "server-file-wrong-size" | | -| UNAUTHENTICATED | "unauthenticated" | | -| UNAUTHORIZED | "unauthorized" | | -| UNAUTHORIZED\_APP | "unauthorized-app" | | -| UNKNOWN | "unknown" | | -| UNSUPPORTED\_ENVIRONMENT | "unsupported-environment" | | - diff --git a/docs-devsite/storage.settablemetadata.md b/docs-devsite/storage.settablemetadata.md deleted file mode 100644 index c721cc6c4f0..00000000000 --- a/docs-devsite/storage.settablemetadata.md +++ /dev/null @@ -1,92 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# SettableMetadata interface -Object metadata that can be set at any time. - -Signature: - -```typescript -export interface SettableMetadata -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [cacheControl](./storage.settablemetadata.md#settablemetadatacachecontrol) | string \| undefined | Served as the 'Cache-Control' header on object download. | -| [contentDisposition](./storage.settablemetadata.md#settablemetadatacontentdisposition) | string \| undefined | Served as the 'Content-Disposition' header on object download. | -| [contentEncoding](./storage.settablemetadata.md#settablemetadatacontentencoding) | string \| undefined | Served as the 'Content-Encoding' header on object download. | -| [contentLanguage](./storage.settablemetadata.md#settablemetadatacontentlanguage) | string \| undefined | Served as the 'Content-Language' header on object download. | -| [contentType](./storage.settablemetadata.md#settablemetadatacontenttype) | string \| undefined | Served as the 'Content-Type' header on object download. | -| [customMetadata](./storage.settablemetadata.md#settablemetadatacustommetadata) | { \[key: string\]: string; } \| undefined | Additional user-defined custom metadata. | - -## SettableMetadata.cacheControl - -Served as the 'Cache-Control' header on object download. - -Signature: - -```typescript -cacheControl?: string | undefined; -``` - -## SettableMetadata.contentDisposition - -Served as the 'Content-Disposition' header on object download. - -Signature: - -```typescript -contentDisposition?: string | undefined; -``` - -## SettableMetadata.contentEncoding - -Served as the 'Content-Encoding' header on object download. - -Signature: - -```typescript -contentEncoding?: string | undefined; -``` - -## SettableMetadata.contentLanguage - -Served as the 'Content-Language' header on object download. - -Signature: - -```typescript -contentLanguage?: string | undefined; -``` - -## SettableMetadata.contentType - -Served as the 'Content-Type' header on object download. - -Signature: - -```typescript -contentType?: string | undefined; -``` - -## SettableMetadata.customMetadata - -Additional user-defined custom metadata. - -Signature: - -```typescript -customMetadata?: { - [key: string]: string; - } | undefined; -``` diff --git a/docs-devsite/storage.storageerror.md b/docs-devsite/storage.storageerror.md deleted file mode 100644 index 9e460e47db7..00000000000 --- a/docs-devsite/storage.storageerror.md +++ /dev/null @@ -1,113 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# StorageError class -An error returned by the Firebase Storage SDK. - -Signature: - -```typescript -export declare class StorageError extends FirebaseError -``` -Extends: [FirebaseError](./util.firebaseerror.md#firebaseerror_class) - -## Constructors - -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(code, message, status\_)](./storage.storageerror.md#storageerrorconstructor) | | Constructs a new instance of the StorageError class | - -## Properties - -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [customData](./storage.storageerror.md#storageerrorcustomdata) | | { serverResponse: string \| null; } | Stores custom error data unique to the StorageError. | -| [serverResponse](./storage.storageerror.md#storageerrorserverresponse) | | null \| string | Optional response message that was added by the server. | -| [status](./storage.storageerror.md#storageerrorstatus) | | number | | - -## Methods - -| Method | Modifiers | Description | -| --- | --- | --- | -| [\_codeEquals(code)](./storage.storageerror.md#storageerror_codeequals) | | Compares a StorageErrorCode against this error's code, filtering out the prefix. | - -## StorageError.(constructor) - -Constructs a new instance of the `StorageError` class - -Signature: - -```typescript -constructor(code: StorageErrorCode, message: string, status_?: number); -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| code | [StorageErrorCode](./storage.md#storageerrorcode) | A StorageErrorCode string to be prefixed with 'storage/' and added to the end of the message. | -| message | string | Error message. | -| status\_ | number | Corresponding HTTP Status Code | - -## StorageError.customData - -Stores custom error data unique to the `StorageError`. - -Signature: - -```typescript -customData: { - serverResponse: string | null; - }; -``` - -## StorageError.serverResponse - -Optional response message that was added by the server. - -Signature: - -```typescript -get serverResponse(): null | string; - -set serverResponse(serverResponse: string | null); -``` - -## StorageError.status - -Signature: - -```typescript -get status(): number; - -set status(status: number); -``` - -## StorageError.\_codeEquals() - -Compares a `StorageErrorCode` against this error's code, filtering out the prefix. - -Signature: - -```typescript -_codeEquals(code: StorageErrorCode): boolean; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| code | [StorageErrorCode](./storage.md#storageerrorcode) | | - -Returns: - -boolean - diff --git a/docs-devsite/storage.storageobserver.md b/docs-devsite/storage.storageobserver.md deleted file mode 100644 index 583ddca7c3d..00000000000 --- a/docs-devsite/storage.storageobserver.md +++ /dev/null @@ -1,51 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# StorageObserver interface -A stream observer for Firebase Storage. - -Signature: - -```typescript -export interface StorageObserver -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [complete](./storage.storageobserver.md#storageobservercomplete) | [CompleteFn](./util.md#completefn) \| null | | -| [error](./storage.storageobserver.md#storageobservererror) | (error: [StorageError](./storage.storageerror.md#storageerror_class)) => void \| null | | -| [next](./storage.storageobserver.md#storageobservernext) | [NextFn](./util.md#nextfn)<T> \| null | | - -## StorageObserver.complete - -Signature: - -```typescript -complete?: CompleteFn | null; -``` - -## StorageObserver.error - -Signature: - -```typescript -error?: (error: StorageError) => void | null; -``` - -## StorageObserver.next - -Signature: - -```typescript -next?: NextFn | null; -``` diff --git a/docs-devsite/storage.storagereference.md b/docs-devsite/storage.storagereference.md deleted file mode 100644 index 4b584a428d5..00000000000 --- a/docs-devsite/storage.storagereference.md +++ /dev/null @@ -1,112 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# StorageReference interface -Represents a reference to a Google Cloud Storage object. Developers can upload, download, and delete objects, as well as get/set object metadata. - -Signature: - -```typescript -export interface StorageReference -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [bucket](./storage.storagereference.md#storagereferencebucket) | string | The name of the bucket containing this reference's object. | -| [fullPath](./storage.storagereference.md#storagereferencefullpath) | string | The full path of this object. | -| [name](./storage.storagereference.md#storagereferencename) | string | The short name of this object, which is the last component of the full path. For example, if fullPath is 'full/path/image.png', name is 'image.png'. | -| [parent](./storage.storagereference.md#storagereferenceparent) | [StorageReference](./storage.storagereference.md#storagereference_interface) \| null | A reference pointing to the parent location of this reference, or null if this reference is the root. | -| [root](./storage.storagereference.md#storagereferenceroot) | [StorageReference](./storage.storagereference.md#storagereference_interface) | A reference to the root of this object's bucket. | -| [storage](./storage.storagereference.md#storagereferencestorage) | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) | The [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance associated with this reference. | - -## Methods - -| Method | Description | -| --- | --- | -| [toString()](./storage.storagereference.md#storagereferencetostring) | Returns a gs:// URL for this object in the form gs://<bucket>/<path>/<to>/<object> | - -## StorageReference.bucket - -The name of the bucket containing this reference's object. - -Signature: - -```typescript -bucket: string; -``` - -## StorageReference.fullPath - -The full path of this object. - -Signature: - -```typescript -fullPath: string; -``` - -## StorageReference.name - -The short name of this object, which is the last component of the full path. For example, if fullPath is 'full/path/image.png', name is 'image.png'. - -Signature: - -```typescript -name: string; -``` - -## StorageReference.parent - -A reference pointing to the parent location of this reference, or null if this reference is the root. - -Signature: - -```typescript -parent: StorageReference | null; -``` - -## StorageReference.root - -A reference to the root of this object's bucket. - -Signature: - -```typescript -root: StorageReference; -``` - -## StorageReference.storage - -The [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance associated with this reference. - -Signature: - -```typescript -storage: FirebaseStorage; -``` - -## StorageReference.toString() - -Returns a gs:// URL for this object in the form `gs://///` - -Signature: - -```typescript -toString(): string; -``` -Returns: - -string - -The gs:// URL. - diff --git a/docs-devsite/storage.uploadmetadata.md b/docs-devsite/storage.uploadmetadata.md deleted file mode 100644 index 2b207401736..00000000000 --- a/docs-devsite/storage.uploadmetadata.md +++ /dev/null @@ -1,36 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# UploadMetadata interface -Object metadata that can be set at upload. - -Signature: - -```typescript -export interface UploadMetadata extends SettableMetadata -``` -Extends: [SettableMetadata](./storage.settablemetadata.md#settablemetadata_interface) - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [md5Hash](./storage.uploadmetadata.md#uploadmetadatamd5hash) | string \| undefined | A Base64-encoded MD5 hash of the object being uploaded. | - -## UploadMetadata.md5Hash - -A Base64-encoded MD5 hash of the object being uploaded. - -Signature: - -```typescript -md5Hash?: string | undefined; -``` diff --git a/docs-devsite/storage.uploadresult.md b/docs-devsite/storage.uploadresult.md deleted file mode 100644 index 05e3542ee62..00000000000 --- a/docs-devsite/storage.uploadresult.md +++ /dev/null @@ -1,46 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# UploadResult interface -Result returned from a non-resumable upload. - -Signature: - -```typescript -export interface UploadResult -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [metadata](./storage.uploadresult.md#uploadresultmetadata) | [FullMetadata](./storage.fullmetadata.md#fullmetadata_interface) | Contains the metadata sent back from the server. | -| [ref](./storage.uploadresult.md#uploadresultref) | [StorageReference](./storage.storagereference.md#storagereference_interface) | The reference that spawned this upload. | - -## UploadResult.metadata - -Contains the metadata sent back from the server. - -Signature: - -```typescript -readonly metadata: FullMetadata; -``` - -## UploadResult.ref - -The reference that spawned this upload. - -Signature: - -```typescript -readonly ref: StorageReference; -``` diff --git a/docs-devsite/storage.uploadtask.md b/docs-devsite/storage.uploadtask.md deleted file mode 100644 index af4bff4088e..00000000000 --- a/docs-devsite/storage.uploadtask.md +++ /dev/null @@ -1,255 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# UploadTask interface -Represents the process of uploading an object. Allows you to monitor and manage the upload. - -Signature: - -```typescript -export interface UploadTask -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [snapshot](./storage.uploadtask.md#uploadtasksnapshot) | [UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface) | A snapshot of the current task state. | - -## Methods - -| Method | Description | -| --- | --- | -| [cancel()](./storage.uploadtask.md#uploadtaskcancel) | Cancels a running task. Has no effect on a complete or failed task. | -| [catch(onRejected)](./storage.uploadtask.md#uploadtaskcatch) | Equivalent to calling then(null, onRejected). | -| [on(event, nextOrObserver, error, complete)](./storage.uploadtask.md#uploadtaskon) | Listens for events on this task.Events have three callback functions (referred to as next, error, and complete).If only the event is passed, a function that can be used to register the callbacks is returned. Otherwise, the callbacks are passed after the event.Callbacks can be passed either as three separate arguments or as the next, error, and complete properties of an object. Any of the three callbacks is optional, as long as at least one is specified. In addition, when you add your callbacks, you get a function back. You can call this function to unregister the associated callbacks. | -| [pause()](./storage.uploadtask.md#uploadtaskpause) | Pauses a currently running task. Has no effect on a paused or failed task. | -| [resume()](./storage.uploadtask.md#uploadtaskresume) | Resumes a paused task. Has no effect on a currently running or failed task. | -| [then(onFulfilled, onRejected)](./storage.uploadtask.md#uploadtaskthen) | This object behaves like a Promise, and resolves with its snapshot data when the upload completes. | - -## UploadTask.snapshot - -A snapshot of the current task state. - -Signature: - -```typescript -snapshot: UploadTaskSnapshot; -``` - -## UploadTask.cancel() - -Cancels a running task. Has no effect on a complete or failed task. - -Signature: - -```typescript -cancel(): boolean; -``` -Returns: - -boolean - -True if the cancel had an effect. - -## UploadTask.catch() - -Equivalent to calling `then(null, onRejected)`. - -Signature: - -```typescript -catch(onRejected: (error: StorageError) => unknown): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| onRejected | (error: [StorageError](./storage.storageerror.md#storageerror_class)) => unknown | | - -Returns: - -Promise<unknown> - -## UploadTask.on() - -Listens for events on this task. - -Events have three callback functions (referred to as `next`, `error`, and `complete`). - -If only the event is passed, a function that can be used to register the callbacks is returned. Otherwise, the callbacks are passed after the event. - -Callbacks can be passed either as three separate arguments or as the `next`, `error`, and `complete` properties of an object. Any of the three callbacks is optional, as long as at least one is specified. In addition, when you add your callbacks, you get a function back. You can call this function to unregister the associated callbacks. - -Signature: - -```typescript -on(event: TaskEvent, nextOrObserver?: StorageObserver | null | ((snapshot: UploadTaskSnapshot) => unknown), error?: ((a: StorageError) => unknown) | null, complete?: Unsubscribe | null): Unsubscribe | Subscribe; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| event | [TaskEvent](./storage.md#taskevent) | The type of event to listen for. | -| nextOrObserver | [StorageObserver](./storage.storageobserver.md#storageobserver_interface)<[UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface)> \| null \| ((snapshot: [UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface)) => unknown) | The next function, which gets called for each item in the event stream, or an observer object with some or all of these three properties (next, error, complete). | -| error | ((a: [StorageError](./storage.storageerror.md#storageerror_class)) => unknown) \| null | A function that gets called with a StorageError if the event stream ends due to an error. | -| complete | [Unsubscribe](./util.md#unsubscribe) \| null | | - -Returns: - -[Unsubscribe](./util.md#unsubscribe) \| [Subscribe](./util.subscribe.md#subscribe_interface)<[UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface)> - -If only the event argument is passed, returns a function you can use to add callbacks (see the examples above). If more than just the event argument is passed, returns a function you can call to unregister the callbacks. - -### Example 1 - -\*\*Pass callbacks separately or in an object.\*\* - -```javascript -var next = function(snapshot) {}; -var error = function(error) {}; -var complete = function() {}; - -// The first example. -uploadTask.on( - firebase.storage.TaskEvent.STATE_CHANGED, - next, - error, - complete); - -// This is equivalent to the first example. -uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED, { - 'next': next, - 'error': error, - 'complete': complete -}); - -// This is equivalent to the first example. -var subscribe = uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED); -subscribe(next, error, complete); - -// This is equivalent to the first example. -var subscribe = uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED); -subscribe({ - 'next': next, - 'error': error, - 'complete': complete -}); - -``` - -### Example 2 - -\*\*Any callback is optional.\*\* - -```javascript -// Just listening for completion, this is legal. -uploadTask.on( - firebase.storage.TaskEvent.STATE_CHANGED, - null, - null, - function() { - console.log('upload complete!'); - }); - -// Just listening for progress/state changes, this is legal. -uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED, function(snapshot) { - var percent = snapshot.bytesTransferred / snapshot.totalBytes * 100; - console.log(percent + "% done"); -}); - -// This is also legal. -uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED, { - 'complete': function() { - console.log('upload complete!'); - } -}); - -``` - -### Example 3 - -\*\*Use the returned function to remove callbacks.\*\* - -```javascript -var unsubscribe = uploadTask.on( - firebase.storage.TaskEvent.STATE_CHANGED, - function(snapshot) { - var percent = snapshot.bytesTransferred / snapshot.totalBytes * 100; - console.log(percent + "% done"); - // Stop after receiving one update. - unsubscribe(); - }); - -// This code is equivalent to the above. -var handle = uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED); -unsubscribe = handle(function(snapshot) { - var percent = snapshot.bytesTransferred / snapshot.totalBytes * 100; - console.log(percent + "% done"); - // Stop after receiving one update. - unsubscribe(); -}); - -``` - -## UploadTask.pause() - -Pauses a currently running task. Has no effect on a paused or failed task. - -Signature: - -```typescript -pause(): boolean; -``` -Returns: - -boolean - -True if the operation took effect, false if ignored. - -## UploadTask.resume() - -Resumes a paused task. Has no effect on a currently running or failed task. - -Signature: - -```typescript -resume(): boolean; -``` -Returns: - -boolean - -True if the operation took effect, false if ignored. - -## UploadTask.then() - -This object behaves like a Promise, and resolves with its snapshot data when the upload completes. - -Signature: - -```typescript -then(onFulfilled?: ((snapshot: UploadTaskSnapshot) => unknown) | null, onRejected?: ((error: StorageError) => unknown) | null): Promise; -``` - -### Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| onFulfilled | ((snapshot: [UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface)) => unknown) \| null | The fulfillment callback. Promise chaining works as normal. | -| onRejected | ((error: [StorageError](./storage.storageerror.md#storageerror_class)) => unknown) \| null | The rejection callback. | - -Returns: - -Promise<unknown> - diff --git a/docs-devsite/storage.uploadtasksnapshot.md b/docs-devsite/storage.uploadtasksnapshot.md deleted file mode 100644 index 351ff7a2154..00000000000 --- a/docs-devsite/storage.uploadtasksnapshot.md +++ /dev/null @@ -1,90 +0,0 @@ -Project: /docs/reference/js/_project.yaml -Book: /docs/reference/_book.yaml -page_type: reference - -{% comment %} -DO NOT EDIT THIS FILE! -This is generated by the JS SDK team, and any local changes will be -overwritten. Changes should be made in the source code at -https://github.com/firebase/firebase-js-sdk -{% endcomment %} - -# UploadTaskSnapshot interface -Holds data about the current state of the upload task. - -Signature: - -```typescript -export interface UploadTaskSnapshot -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [bytesTransferred](./storage.uploadtasksnapshot.md#uploadtasksnapshotbytestransferred) | number | The number of bytes that have been successfully uploaded so far. | -| [metadata](./storage.uploadtasksnapshot.md#uploadtasksnapshotmetadata) | [FullMetadata](./storage.fullmetadata.md#fullmetadata_interface) | Before the upload completes, contains the metadata sent to the server. After the upload completes, contains the metadata sent back from the server. | -| [ref](./storage.uploadtasksnapshot.md#uploadtasksnapshotref) | [StorageReference](./storage.storagereference.md#storagereference_interface) | The reference that spawned this snapshot's upload task. | -| [state](./storage.uploadtasksnapshot.md#uploadtasksnapshotstate) | [TaskState](./storage.md#taskstate) | The current state of the task. | -| [task](./storage.uploadtasksnapshot.md#uploadtasksnapshottask) | [UploadTask](./storage.uploadtask.md#uploadtask_interface) | The task of which this is a snapshot. | -| [totalBytes](./storage.uploadtasksnapshot.md#uploadtasksnapshottotalbytes) | number | The total number of bytes to be uploaded. | - -## UploadTaskSnapshot.bytesTransferred - -The number of bytes that have been successfully uploaded so far. - -Signature: - -```typescript -bytesTransferred: number; -``` - -## UploadTaskSnapshot.metadata - -Before the upload completes, contains the metadata sent to the server. After the upload completes, contains the metadata sent back from the server. - -Signature: - -```typescript -metadata: FullMetadata; -``` - -## UploadTaskSnapshot.ref - -The reference that spawned this snapshot's upload task. - -Signature: - -```typescript -ref: StorageReference; -``` - -## UploadTaskSnapshot.state - -The current state of the task. - -Signature: - -```typescript -state: TaskState; -``` - -## UploadTaskSnapshot.task - -The task of which this is a snapshot. - -Signature: - -```typescript -task: UploadTask; -``` - -## UploadTaskSnapshot.totalBytes - -The total number of bytes to be uploaded. - -Signature: - -```typescript -totalBytes: number; -``` From b3d0c677eb0770d78826f252283972b8f69e250c Mon Sep 17 00:00:00 2001 From: Christina Holland Date: Mon, 13 Feb 2023 15:17:06 -0800 Subject: [PATCH 08/12] add docs-devsite from master --- common/api-review/auth.api.md | 27 +- docs-devsite/analytics.analytics.md | 35 + .../analytics.analyticscalloptions.md | 35 + docs-devsite/analytics.analyticssettings.md | 35 + docs-devsite/analytics.consentsettings.md | 79 + docs-devsite/analytics.controlparams.md | 60 + docs-devsite/analytics.customparams.md | 19 + docs-devsite/analytics.eventparams.md | 316 +++ docs-devsite/analytics.gtagconfigparams.md | 134 ++ docs-devsite/analytics.item.md | 278 +++ docs-devsite/analytics.md | 991 ++++++++ docs-devsite/analytics.promotion.md | 65 + docs-devsite/analytics.settingsoptions.md | 46 + docs-devsite/app-check.appcheck.md | 35 + docs-devsite/app-check.appcheckoptions.md | 46 + docs-devsite/app-check.appchecktoken.md | 44 + docs-devsite/app-check.appchecktokenresult.md | 35 + docs-devsite/app-check.customprovider.md | 43 + .../app-check.customprovideroptions.md | 35 + docs-devsite/app-check.md | 170 ++ .../app-check.recaptchaenterpriseprovider.md | 43 + docs-devsite/app-check.recaptchav3provider.md | 43 + docs-devsite/app.firebaseapp.md | 91 + docs-devsite/app.firebaseappsettings.md | 46 + docs-devsite/app.firebaseoptions.md | 112 + docs-devsite/app.md | 306 +++ docs-devsite/auth.actioncodeinfo.md | 58 + docs-devsite/auth.actioncodesettings.md | 95 + docs-devsite/auth.actioncodeurl.md | 121 + docs-devsite/auth.additionaluserinfo.md | 68 + docs-devsite/auth.applicationverifier.md | 59 + docs-devsite/auth.auth.md | 299 +++ docs-devsite/auth.authcredential.md | 76 + docs-devsite/auth.autherror.md | 41 + docs-devsite/auth.autherrormap.md | 27 + docs-devsite/auth.authprovider.md | 35 + docs-devsite/auth.authsettings.md | 41 + docs-devsite/auth.config.md | 90 + docs-devsite/auth.confirmationresult.md | 74 + docs-devsite/auth.dependencies.md | 63 + docs-devsite/auth.emailauthcredential.md | 69 + docs-devsite/auth.emailauthprovider.md | 159 ++ docs-devsite/auth.emulatorconfig.md | 70 + docs-devsite/auth.facebookauthprovider.md | 182 ++ docs-devsite/auth.githubauthprovider.md | 174 ++ docs-devsite/auth.googleauthprovider.md | 185 ++ docs-devsite/auth.idtokenresult.md | 109 + docs-devsite/auth.md | 1992 +++++++++++++++ docs-devsite/auth.multifactorassertion.md | 37 + docs-devsite/auth.multifactorerror.md | 67 + docs-devsite/auth.multifactorinfo.md | 68 + docs-devsite/auth.multifactorresolver.md | 128 + docs-devsite/auth.multifactorsession.md | 19 + docs-devsite/auth.multifactoruser.md | 161 ++ docs-devsite/auth.oauthcredential.md | 105 + docs-devsite/auth.oauthcredentialoptions.md | 61 + docs-devsite/auth.oauthprovider.md | 168 ++ docs-devsite/auth.parsedtoken.md | 83 + docs-devsite/auth.persistence.md | 35 + docs-devsite/auth.phoneauthcredential.md | 63 + docs-devsite/auth.phoneauthprovider.md | 256 ++ .../auth.phonemultifactorassertion.md | 21 + .../auth.phonemultifactorenrollinfooptions.md | 46 + .../auth.phonemultifactorgenerator.md | 64 + docs-devsite/auth.phonemultifactorinfo.md | 36 + .../auth.phonemultifactorsignininfooptions.md | 61 + .../auth.phonesinglefactorinfooptions.md | 35 + docs-devsite/auth.popupredirectresolver.md | 19 + docs-devsite/auth.reactnativeasyncstorage.md | 89 + docs-devsite/auth.recaptchaparameters.md | 23 + docs-devsite/auth.recaptchaverifier.md | 116 + docs-devsite/auth.samlauthprovider.md | 119 + docs-devsite/auth.twitterauthprovider.md | 173 ++ docs-devsite/auth.user.md | 204 ++ docs-devsite/auth.usercredential.md | 59 + docs-devsite/auth.userinfo.md | 92 + docs-devsite/auth.usermetadata.md | 46 + docs-devsite/database.database.md | 46 + docs-devsite/database.databasereference.md | 68 + docs-devsite/database.datasnapshot.md | 237 ++ docs-devsite/database.listenoptions.md | 35 + docs-devsite/database.md | 1405 +++++++++++ docs-devsite/database.ondisconnect.md | 143 ++ docs-devsite/database.query.md | 108 + docs-devsite/database.queryconstraint.md | 35 + docs-devsite/database.thenablereference.md | 21 + docs-devsite/database.transactionoptions.md | 35 + docs-devsite/database.transactionresult.md | 66 + docs-devsite/firestore.md | 19 + docs-devsite/firestore_.aggregatefield.md | 35 + .../firestore_.aggregatequerysnapshot.md | 70 + docs-devsite/firestore_.aggregatespec.md | 19 + docs-devsite/firestore_.bytes.md | 138 ++ .../firestore_.collectionreference.md | 121 + docs-devsite/firestore_.documentchange.md | 68 + docs-devsite/firestore_.documentdata.md | 19 + docs-devsite/firestore_.documentreference.md | 142 ++ docs-devsite/firestore_.documentsnapshot.md | 146 ++ docs-devsite/firestore_.fieldpath.md | 72 + docs-devsite/firestore_.fieldvalue.md | 46 + docs-devsite/firestore_.firestore.md | 68 + .../firestore_.firestoredataconverter.md | 134 ++ docs-devsite/firestore_.firestoreerror.md | 58 + docs-devsite/firestore_.firestoresettings.md | 96 + docs-devsite/firestore_.geopoint.md | 117 + docs-devsite/firestore_.index.md | 55 + docs-devsite/firestore_.indexconfiguration.md | 43 + docs-devsite/firestore_.indexfield.md | 73 + docs-devsite/firestore_.loadbundletask.md | 94 + .../firestore_.loadbundletaskprogress.md | 79 + docs-devsite/firestore_.md | 2134 +++++++++++++++++ .../firestore_.persistencesettings.md | 35 + docs-devsite/firestore_.query.md | 125 + docs-devsite/firestore_.queryconstraint.md | 35 + .../firestore_.querydocumentsnapshot.md | 54 + .../firestore_.queryendatconstraint.md | 36 + .../firestore_.queryfieldfilterconstraint.md | 36 + .../firestore_.querylimitconstraint.md | 36 + .../firestore_.queryorderbyconstraint.md | 38 + docs-devsite/firestore_.querysnapshot.md | 128 + .../firestore_.querystartatconstraint.md | 36 + .../firestore_.snapshotlistenoptions.md | 35 + docs-devsite/firestore_.snapshotmetadata.md | 75 + docs-devsite/firestore_.snapshotoptions.md | 41 + docs-devsite/firestore_.timestamp.md | 243 ++ docs-devsite/firestore_.transaction.md | 190 ++ docs-devsite/firestore_.transactionoptions.md | 35 + docs-devsite/firestore_.unsubscribe.md | 19 + docs-devsite/firestore_.writebatch.md | 181 ++ docs-devsite/firestore_lite.aggregatefield.md | 35 + .../firestore_lite.aggregatequerysnapshot.md | 70 + docs-devsite/firestore_lite.aggregatespec.md | 19 + docs-devsite/firestore_lite.bytes.md | 138 ++ .../firestore_lite.collectionreference.md | 121 + docs-devsite/firestore_lite.documentdata.md | 19 + .../firestore_lite.documentreference.md | 142 ++ .../firestore_lite.documentsnapshot.md | 125 + docs-devsite/firestore_lite.fieldpath.md | 72 + docs-devsite/firestore_lite.fieldvalue.md | 46 + docs-devsite/firestore_lite.firestore.md | 68 + .../firestore_lite.firestoredataconverter.md | 130 + docs-devsite/firestore_lite.firestoreerror.md | 58 + docs-devsite/firestore_lite.geopoint.md | 117 + docs-devsite/firestore_lite.md | 1443 +++++++++++ docs-devsite/firestore_lite.query.md | 125 + .../firestore_lite.queryconstraint.md | 35 + .../firestore_lite.querydocumentsnapshot.md | 45 + .../firestore_lite.queryendatconstraint.md | 36 + ...restore_lite.queryfieldfilterconstraint.md | 36 + .../firestore_lite.querylimitconstraint.md | 36 + .../firestore_lite.queryorderbyconstraint.md | 38 + docs-devsite/firestore_lite.querysnapshot.md | 96 + .../firestore_lite.querystartatconstraint.md | 36 + docs-devsite/firestore_lite.settings.md | 57 + docs-devsite/firestore_lite.timestamp.md | 243 ++ docs-devsite/firestore_lite.transaction.md | 190 ++ .../firestore_lite.transactionoptions.md | 35 + docs-devsite/firestore_lite.writebatch.md | 181 ++ docs-devsite/functions.functions.md | 57 + docs-devsite/functions.functionserror.md | 47 + .../functions.httpscallableoptions.md | 35 + docs-devsite/functions.httpscallableresult.md | 35 + docs-devsite/functions.md | 162 ++ docs-devsite/index.md | 30 + docs-devsite/installations.installations.md | 35 + docs-devsite/installations.md | 162 ++ docs-devsite/messaging.md | 19 + docs-devsite/messaging_.fcmoptions.md | 46 + docs-devsite/messaging_.gettokenoptions.md | 46 + docs-devsite/messaging_.md | 143 ++ docs-devsite/messaging_.messagepayload.md | 92 + docs-devsite/messaging_.messaging.md | 35 + .../messaging_.notificationpayload.md | 68 + docs-devsite/messaging_sw.fcmoptions.md | 46 + docs-devsite/messaging_sw.gettokenoptions.md | 46 + docs-devsite/messaging_sw.md | 116 + docs-devsite/messaging_sw.messagepayload.md | 92 + docs-devsite/messaging_sw.messaging.md | 35 + .../messaging_sw.notificationpayload.md | 68 + .../performance.firebaseperformance.md | 57 + docs-devsite/performance.md | 94 + .../performance.performancesettings.md | 46 + docs-devsite/performance.performancetrace.md | 228 ++ docs-devsite/remote-config.md | 345 +++ docs-devsite/remote-config.remoteconfig.md | 81 + .../remote-config.remoteconfigsettings.md | 46 + docs-devsite/remote-config.value.md | 83 + docs-devsite/storage.firebasestorage.md | 58 + docs-devsite/storage.fullmetadata.md | 135 ++ docs-devsite/storage.listoptions.md | 46 + docs-devsite/storage.listresult.md | 59 + docs-devsite/storage.md | 550 +++++ docs-devsite/storage.settablemetadata.md | 92 + docs-devsite/storage.storageerror.md | 113 + docs-devsite/storage.storageobserver.md | 51 + docs-devsite/storage.storagereference.md | 112 + docs-devsite/storage.uploadmetadata.md | 36 + docs-devsite/storage.uploadresult.md | 46 + docs-devsite/storage.uploadtask.md | 255 ++ docs-devsite/storage.uploadtasksnapshot.md | 90 + 200 files changed, 24945 insertions(+), 18 deletions(-) create mode 100644 docs-devsite/analytics.analytics.md create mode 100644 docs-devsite/analytics.analyticscalloptions.md create mode 100644 docs-devsite/analytics.analyticssettings.md create mode 100644 docs-devsite/analytics.consentsettings.md create mode 100644 docs-devsite/analytics.controlparams.md create mode 100644 docs-devsite/analytics.customparams.md create mode 100644 docs-devsite/analytics.eventparams.md create mode 100644 docs-devsite/analytics.gtagconfigparams.md create mode 100644 docs-devsite/analytics.item.md create mode 100644 docs-devsite/analytics.md create mode 100644 docs-devsite/analytics.promotion.md create mode 100644 docs-devsite/analytics.settingsoptions.md create mode 100644 docs-devsite/app-check.appcheck.md create mode 100644 docs-devsite/app-check.appcheckoptions.md create mode 100644 docs-devsite/app-check.appchecktoken.md create mode 100644 docs-devsite/app-check.appchecktokenresult.md create mode 100644 docs-devsite/app-check.customprovider.md create mode 100644 docs-devsite/app-check.customprovideroptions.md create mode 100644 docs-devsite/app-check.md create mode 100644 docs-devsite/app-check.recaptchaenterpriseprovider.md create mode 100644 docs-devsite/app-check.recaptchav3provider.md create mode 100644 docs-devsite/app.firebaseapp.md create mode 100644 docs-devsite/app.firebaseappsettings.md create mode 100644 docs-devsite/app.firebaseoptions.md create mode 100644 docs-devsite/app.md create mode 100644 docs-devsite/auth.actioncodeinfo.md create mode 100644 docs-devsite/auth.actioncodesettings.md create mode 100644 docs-devsite/auth.actioncodeurl.md create mode 100644 docs-devsite/auth.additionaluserinfo.md create mode 100644 docs-devsite/auth.applicationverifier.md create mode 100644 docs-devsite/auth.auth.md create mode 100644 docs-devsite/auth.authcredential.md create mode 100644 docs-devsite/auth.autherror.md create mode 100644 docs-devsite/auth.autherrormap.md create mode 100644 docs-devsite/auth.authprovider.md create mode 100644 docs-devsite/auth.authsettings.md create mode 100644 docs-devsite/auth.config.md create mode 100644 docs-devsite/auth.confirmationresult.md create mode 100644 docs-devsite/auth.dependencies.md create mode 100644 docs-devsite/auth.emailauthcredential.md create mode 100644 docs-devsite/auth.emailauthprovider.md create mode 100644 docs-devsite/auth.emulatorconfig.md create mode 100644 docs-devsite/auth.facebookauthprovider.md create mode 100644 docs-devsite/auth.githubauthprovider.md create mode 100644 docs-devsite/auth.googleauthprovider.md create mode 100644 docs-devsite/auth.idtokenresult.md create mode 100644 docs-devsite/auth.md create mode 100644 docs-devsite/auth.multifactorassertion.md create mode 100644 docs-devsite/auth.multifactorerror.md create mode 100644 docs-devsite/auth.multifactorinfo.md create mode 100644 docs-devsite/auth.multifactorresolver.md create mode 100644 docs-devsite/auth.multifactorsession.md create mode 100644 docs-devsite/auth.multifactoruser.md create mode 100644 docs-devsite/auth.oauthcredential.md create mode 100644 docs-devsite/auth.oauthcredentialoptions.md create mode 100644 docs-devsite/auth.oauthprovider.md create mode 100644 docs-devsite/auth.parsedtoken.md create mode 100644 docs-devsite/auth.persistence.md create mode 100644 docs-devsite/auth.phoneauthcredential.md create mode 100644 docs-devsite/auth.phoneauthprovider.md create mode 100644 docs-devsite/auth.phonemultifactorassertion.md create mode 100644 docs-devsite/auth.phonemultifactorenrollinfooptions.md create mode 100644 docs-devsite/auth.phonemultifactorgenerator.md create mode 100644 docs-devsite/auth.phonemultifactorinfo.md create mode 100644 docs-devsite/auth.phonemultifactorsignininfooptions.md create mode 100644 docs-devsite/auth.phonesinglefactorinfooptions.md create mode 100644 docs-devsite/auth.popupredirectresolver.md create mode 100644 docs-devsite/auth.reactnativeasyncstorage.md create mode 100644 docs-devsite/auth.recaptchaparameters.md create mode 100644 docs-devsite/auth.recaptchaverifier.md create mode 100644 docs-devsite/auth.samlauthprovider.md create mode 100644 docs-devsite/auth.twitterauthprovider.md create mode 100644 docs-devsite/auth.user.md create mode 100644 docs-devsite/auth.usercredential.md create mode 100644 docs-devsite/auth.userinfo.md create mode 100644 docs-devsite/auth.usermetadata.md create mode 100644 docs-devsite/database.database.md create mode 100644 docs-devsite/database.databasereference.md create mode 100644 docs-devsite/database.datasnapshot.md create mode 100644 docs-devsite/database.listenoptions.md create mode 100644 docs-devsite/database.md create mode 100644 docs-devsite/database.ondisconnect.md create mode 100644 docs-devsite/database.query.md create mode 100644 docs-devsite/database.queryconstraint.md create mode 100644 docs-devsite/database.thenablereference.md create mode 100644 docs-devsite/database.transactionoptions.md create mode 100644 docs-devsite/database.transactionresult.md create mode 100644 docs-devsite/firestore.md create mode 100644 docs-devsite/firestore_.aggregatefield.md create mode 100644 docs-devsite/firestore_.aggregatequerysnapshot.md create mode 100644 docs-devsite/firestore_.aggregatespec.md create mode 100644 docs-devsite/firestore_.bytes.md create mode 100644 docs-devsite/firestore_.collectionreference.md create mode 100644 docs-devsite/firestore_.documentchange.md create mode 100644 docs-devsite/firestore_.documentdata.md create mode 100644 docs-devsite/firestore_.documentreference.md create mode 100644 docs-devsite/firestore_.documentsnapshot.md create mode 100644 docs-devsite/firestore_.fieldpath.md create mode 100644 docs-devsite/firestore_.fieldvalue.md create mode 100644 docs-devsite/firestore_.firestore.md create mode 100644 docs-devsite/firestore_.firestoredataconverter.md create mode 100644 docs-devsite/firestore_.firestoreerror.md create mode 100644 docs-devsite/firestore_.firestoresettings.md create mode 100644 docs-devsite/firestore_.geopoint.md create mode 100644 docs-devsite/firestore_.index.md create mode 100644 docs-devsite/firestore_.indexconfiguration.md create mode 100644 docs-devsite/firestore_.indexfield.md create mode 100644 docs-devsite/firestore_.loadbundletask.md create mode 100644 docs-devsite/firestore_.loadbundletaskprogress.md create mode 100644 docs-devsite/firestore_.md create mode 100644 docs-devsite/firestore_.persistencesettings.md create mode 100644 docs-devsite/firestore_.query.md create mode 100644 docs-devsite/firestore_.queryconstraint.md create mode 100644 docs-devsite/firestore_.querydocumentsnapshot.md create mode 100644 docs-devsite/firestore_.queryendatconstraint.md create mode 100644 docs-devsite/firestore_.queryfieldfilterconstraint.md create mode 100644 docs-devsite/firestore_.querylimitconstraint.md create mode 100644 docs-devsite/firestore_.queryorderbyconstraint.md create mode 100644 docs-devsite/firestore_.querysnapshot.md create mode 100644 docs-devsite/firestore_.querystartatconstraint.md create mode 100644 docs-devsite/firestore_.snapshotlistenoptions.md create mode 100644 docs-devsite/firestore_.snapshotmetadata.md create mode 100644 docs-devsite/firestore_.snapshotoptions.md create mode 100644 docs-devsite/firestore_.timestamp.md create mode 100644 docs-devsite/firestore_.transaction.md create mode 100644 docs-devsite/firestore_.transactionoptions.md create mode 100644 docs-devsite/firestore_.unsubscribe.md create mode 100644 docs-devsite/firestore_.writebatch.md create mode 100644 docs-devsite/firestore_lite.aggregatefield.md create mode 100644 docs-devsite/firestore_lite.aggregatequerysnapshot.md create mode 100644 docs-devsite/firestore_lite.aggregatespec.md create mode 100644 docs-devsite/firestore_lite.bytes.md create mode 100644 docs-devsite/firestore_lite.collectionreference.md create mode 100644 docs-devsite/firestore_lite.documentdata.md create mode 100644 docs-devsite/firestore_lite.documentreference.md create mode 100644 docs-devsite/firestore_lite.documentsnapshot.md create mode 100644 docs-devsite/firestore_lite.fieldpath.md create mode 100644 docs-devsite/firestore_lite.fieldvalue.md create mode 100644 docs-devsite/firestore_lite.firestore.md create mode 100644 docs-devsite/firestore_lite.firestoredataconverter.md create mode 100644 docs-devsite/firestore_lite.firestoreerror.md create mode 100644 docs-devsite/firestore_lite.geopoint.md create mode 100644 docs-devsite/firestore_lite.md create mode 100644 docs-devsite/firestore_lite.query.md create mode 100644 docs-devsite/firestore_lite.queryconstraint.md create mode 100644 docs-devsite/firestore_lite.querydocumentsnapshot.md create mode 100644 docs-devsite/firestore_lite.queryendatconstraint.md create mode 100644 docs-devsite/firestore_lite.queryfieldfilterconstraint.md create mode 100644 docs-devsite/firestore_lite.querylimitconstraint.md create mode 100644 docs-devsite/firestore_lite.queryorderbyconstraint.md create mode 100644 docs-devsite/firestore_lite.querysnapshot.md create mode 100644 docs-devsite/firestore_lite.querystartatconstraint.md create mode 100644 docs-devsite/firestore_lite.settings.md create mode 100644 docs-devsite/firestore_lite.timestamp.md create mode 100644 docs-devsite/firestore_lite.transaction.md create mode 100644 docs-devsite/firestore_lite.transactionoptions.md create mode 100644 docs-devsite/firestore_lite.writebatch.md create mode 100644 docs-devsite/functions.functions.md create mode 100644 docs-devsite/functions.functionserror.md create mode 100644 docs-devsite/functions.httpscallableoptions.md create mode 100644 docs-devsite/functions.httpscallableresult.md create mode 100644 docs-devsite/functions.md create mode 100644 docs-devsite/index.md create mode 100644 docs-devsite/installations.installations.md create mode 100644 docs-devsite/installations.md create mode 100644 docs-devsite/messaging.md create mode 100644 docs-devsite/messaging_.fcmoptions.md create mode 100644 docs-devsite/messaging_.gettokenoptions.md create mode 100644 docs-devsite/messaging_.md create mode 100644 docs-devsite/messaging_.messagepayload.md create mode 100644 docs-devsite/messaging_.messaging.md create mode 100644 docs-devsite/messaging_.notificationpayload.md create mode 100644 docs-devsite/messaging_sw.fcmoptions.md create mode 100644 docs-devsite/messaging_sw.gettokenoptions.md create mode 100644 docs-devsite/messaging_sw.md create mode 100644 docs-devsite/messaging_sw.messagepayload.md create mode 100644 docs-devsite/messaging_sw.messaging.md create mode 100644 docs-devsite/messaging_sw.notificationpayload.md create mode 100644 docs-devsite/performance.firebaseperformance.md create mode 100644 docs-devsite/performance.md create mode 100644 docs-devsite/performance.performancesettings.md create mode 100644 docs-devsite/performance.performancetrace.md create mode 100644 docs-devsite/remote-config.md create mode 100644 docs-devsite/remote-config.remoteconfig.md create mode 100644 docs-devsite/remote-config.remoteconfigsettings.md create mode 100644 docs-devsite/remote-config.value.md create mode 100644 docs-devsite/storage.firebasestorage.md create mode 100644 docs-devsite/storage.fullmetadata.md create mode 100644 docs-devsite/storage.listoptions.md create mode 100644 docs-devsite/storage.listresult.md create mode 100644 docs-devsite/storage.md create mode 100644 docs-devsite/storage.settablemetadata.md create mode 100644 docs-devsite/storage.storageerror.md create mode 100644 docs-devsite/storage.storageobserver.md create mode 100644 docs-devsite/storage.storagereference.md create mode 100644 docs-devsite/storage.uploadmetadata.md create mode 100644 docs-devsite/storage.uploadresult.md create mode 100644 docs-devsite/storage.uploadtask.md create mode 100644 docs-devsite/storage.uploadtasksnapshot.md diff --git a/common/api-review/auth.api.md b/common/api-review/auth.api.md index cf25749656c..045b64bcf19 100644 --- a/common/api-review/auth.api.md +++ b/common/api-review/auth.api.md @@ -103,14 +103,14 @@ export class AuthCredential { protected constructor( providerId: string, signInMethod: string); - // Warning: (ae-forgotten-export) The symbol "AuthInternal" needs to be exported by the entry point index.doc.d.ts - // Warning: (ae-forgotten-export) The symbol "PhoneOrOauthTokenResponse" needs to be exported by the entry point index.doc.d.ts + // Warning: (ae-forgotten-export) The symbol "AuthInternal" needs to be exported by the entry point index.d.ts + // Warning: (ae-forgotten-export) The symbol "PhoneOrOauthTokenResponse" needs to be exported by the entry point index.d.ts // // @internal (undocumented) _getIdTokenResponse(_auth: AuthInternal): Promise; // @internal (undocumented) _getReauthenticationResolver(_auth: AuthInternal): Promise; - // Warning: (ae-forgotten-export) The symbol "IdTokenResponse" needs to be exported by the entry point index.doc.d.ts + // Warning: (ae-forgotten-export) The symbol "IdTokenResponse" needs to be exported by the entry point index.d.ts // // @internal (undocumented) _linkToIdToken(_auth: AuthInternal, _idToken: string): Promise; @@ -283,9 +283,6 @@ export function connectAuthEmulator(auth: Auth, url: string, options?: { disableWarnings: boolean; }): void; -// @public -export const cordovaPopupRedirectResolver: PopupRedirectResolver; - // @public export function createUserWithEmailAndPassword(auth: Auth, email: string, password: string): Promise; @@ -349,7 +346,7 @@ export interface EmulatorConfig { export { ErrorFn } -// Warning: (ae-forgotten-export) The symbol "BaseOAuthProvider" needs to be exported by the entry point index.doc.d.ts +// Warning: (ae-forgotten-export) The symbol "BaseOAuthProvider" needs to be exported by the entry point index.d.ts // // @public export class FacebookAuthProvider extends BaseOAuthProvider { @@ -384,9 +381,6 @@ export function getIdTokenResult(user: User, forceRefresh?: boolean): Promise; @@ -496,7 +490,7 @@ export type NextOrObserver = NextFn | Observer; export class OAuthCredential extends AuthCredential { accessToken?: string; static fromJSON(json: string | object): OAuthCredential | null; - // Warning: (ae-forgotten-export) The symbol "OAuthCredentialParams" needs to be exported by the entry point index.doc.d.ts + // Warning: (ae-forgotten-export) The symbol "OAuthCredentialParams" needs to be exported by the entry point index.d.ts // // @internal (undocumented) static _fromParams(params: OAuthCredentialParams): OAuthCredential; @@ -574,7 +568,7 @@ export class PhoneAuthCredential extends AuthCredential { _getReauthenticationResolver(auth: AuthInternal): Promise; // @internal (undocumented) _linkToIdToken(auth: AuthInternal, idToken: string): Promise; - // Warning: (ae-forgotten-export) The symbol "SignInWithPhoneNumberRequest" needs to be exported by the entry point index.doc.d.ts + // Warning: (ae-forgotten-export) The symbol "SignInWithPhoneNumberRequest" needs to be exported by the entry point index.d.ts // // @internal (undocumented) _makeVerificationRequest(): SignInWithPhoneNumberRequest; @@ -653,9 +647,6 @@ export interface ReactNativeAsyncStorage { setItem(key: string, value: string): Promise; } -// @public -export const reactNativeLocalPersistence: Persistence; - // @public export function reauthenticateWithCredential(user: User, credential: AuthCredential): Promise; @@ -674,13 +665,13 @@ export interface RecaptchaParameters { [key: string]: any; } -// Warning: (ae-forgotten-export) The symbol "ApplicationVerifierInternal" needs to be exported by the entry point index.doc.d.ts +// Warning: (ae-forgotten-export) The symbol "ApplicationVerifierInternal" needs to be exported by the entry point index.d.ts // // @public export class RecaptchaVerifier implements ApplicationVerifierInternal { constructor(containerOrId: HTMLElement | string, parameters: RecaptchaParameters, authExtern: Auth); clear(): void; - // Warning: (ae-forgotten-export) The symbol "ReCaptchaLoader" needs to be exported by the entry point index.doc.d.ts + // Warning: (ae-forgotten-export) The symbol "ReCaptchaLoader" needs to be exported by the entry point index.d.ts // // @internal (undocumented) readonly _recaptchaLoader: ReCaptchaLoader; @@ -694,7 +685,7 @@ export class RecaptchaVerifier implements ApplicationVerifierInternal { // @public export function reload(user: User): Promise; -// Warning: (ae-forgotten-export) The symbol "FederatedAuthProvider" needs to be exported by the entry point index.doc.d.ts +// Warning: (ae-forgotten-export) The symbol "FederatedAuthProvider" needs to be exported by the entry point index.d.ts // // @public export class SAMLAuthProvider extends FederatedAuthProvider { diff --git a/docs-devsite/analytics.analytics.md b/docs-devsite/analytics.analytics.md new file mode 100644 index 00000000000..dcf0038f2d9 --- /dev/null +++ b/docs-devsite/analytics.analytics.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Analytics interface +An instance of Firebase Analytics. + +Signature: + +```typescript +export interface Analytics +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [app](./analytics.analytics.md#analyticsapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this [Analytics](./analytics.analytics.md#analytics_interface) instance is associated with. | + +## Analytics.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this [Analytics](./analytics.analytics.md#analytics_interface) instance is associated with. + +Signature: + +```typescript +app: FirebaseApp; +``` diff --git a/docs-devsite/analytics.analyticscalloptions.md b/docs-devsite/analytics.analyticscalloptions.md new file mode 100644 index 00000000000..d89863bcfa6 --- /dev/null +++ b/docs-devsite/analytics.analyticscalloptions.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AnalyticsCallOptions interface +Additional options that can be passed to Analytics method calls such as `logEvent`, etc. + +Signature: + +```typescript +export interface AnalyticsCallOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [global](./analytics.analyticscalloptions.md#analyticscalloptionsglobal) | boolean | If true, this config or event call applies globally to all Google Analytics properties on the page. | + +## AnalyticsCallOptions.global + +If true, this config or event call applies globally to all Google Analytics properties on the page. + +Signature: + +```typescript +global: boolean; +``` diff --git a/docs-devsite/analytics.analyticssettings.md b/docs-devsite/analytics.analyticssettings.md new file mode 100644 index 00000000000..3ee67d8456d --- /dev/null +++ b/docs-devsite/analytics.analyticssettings.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AnalyticsSettings interface +[Analytics](./analytics.analytics.md#analytics_interface) instance initialization options. + +Signature: + +```typescript +export interface AnalyticsSettings +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [config](./analytics.analyticssettings.md#analyticssettingsconfig) | [GtagConfigParams](./analytics.gtagconfigparams.md#gtagconfigparams_interface) \| [EventParams](./analytics.eventparams.md#eventparams_interface) | Params to be passed in the initial gtag config call during Firebase Analytics initialization. | + +## AnalyticsSettings.config + +Params to be passed in the initial `gtag` config call during Firebase Analytics initialization. + +Signature: + +```typescript +config?: GtagConfigParams | EventParams; +``` diff --git a/docs-devsite/analytics.consentsettings.md b/docs-devsite/analytics.consentsettings.md new file mode 100644 index 00000000000..975d51d8bc6 --- /dev/null +++ b/docs-devsite/analytics.consentsettings.md @@ -0,0 +1,79 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ConsentSettings interface +Consent status settings for each consent type. For more information, see [the GA4 reference documentation for consent state and consent types](https://developers.google.com/tag-platform/tag-manager/templates/consent-apis). + +Signature: + +```typescript +export interface ConsentSettings +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [ad\_storage](./analytics.consentsettings.md#consentsettingsad_storage) | [ConsentStatusString](./analytics.md#consentstatusstring) | Enables storage, such as cookies, related to advertising | +| [analytics\_storage](./analytics.consentsettings.md#consentsettingsanalytics_storage) | [ConsentStatusString](./analytics.md#consentstatusstring) | Enables storage, such as cookies, related to analytics (for example, visit duration) | +| [functionality\_storage](./analytics.consentsettings.md#consentsettingsfunctionality_storage) | [ConsentStatusString](./analytics.md#consentstatusstring) | Enables storage that supports the functionality of the website or app such as language settings | +| [personalization\_storage](./analytics.consentsettings.md#consentsettingspersonalization_storage) | [ConsentStatusString](./analytics.md#consentstatusstring) | Enables storage related to personalization such as video recommendations | +| [security\_storage](./analytics.consentsettings.md#consentsettingssecurity_storage) | [ConsentStatusString](./analytics.md#consentstatusstring) | Enables storage related to security such as authentication functionality, fraud prevention, and other user protection. | + +## ConsentSettings.ad\_storage + +Enables storage, such as cookies, related to advertising + +Signature: + +```typescript +ad_storage?: ConsentStatusString; +``` + +## ConsentSettings.analytics\_storage + +Enables storage, such as cookies, related to analytics (for example, visit duration) + +Signature: + +```typescript +analytics_storage?: ConsentStatusString; +``` + +## ConsentSettings.functionality\_storage + +Enables storage that supports the functionality of the website or app such as language settings + +Signature: + +```typescript +functionality_storage?: ConsentStatusString; +``` + +## ConsentSettings.personalization\_storage + +Enables storage related to personalization such as video recommendations + +Signature: + +```typescript +personalization_storage?: ConsentStatusString; +``` + +## ConsentSettings.security\_storage + +Enables storage related to security such as authentication functionality, fraud prevention, and other user protection. + +Signature: + +```typescript +security_storage?: ConsentStatusString; +``` diff --git a/docs-devsite/analytics.controlparams.md b/docs-devsite/analytics.controlparams.md new file mode 100644 index 00000000000..d7dfea1460c --- /dev/null +++ b/docs-devsite/analytics.controlparams.md @@ -0,0 +1,60 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ControlParams interface +Standard `gtag.js` control parameters. For more information, see [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export interface ControlParams +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [event\_callback](./analytics.controlparams.md#controlparamsevent_callback) | () => void | | +| [event\_timeout](./analytics.controlparams.md#controlparamsevent_timeout) | number | | +| [groups](./analytics.controlparams.md#controlparamsgroups) | string \| string\[\] | | +| [send\_to](./analytics.controlparams.md#controlparamssend_to) | string \| string\[\] | | + +## ControlParams.event\_callback + +Signature: + +```typescript +event_callback?: () => void; +``` + +## ControlParams.event\_timeout + +Signature: + +```typescript +event_timeout?: number; +``` + +## ControlParams.groups + +Signature: + +```typescript +groups?: string | string[]; +``` + +## ControlParams.send\_to + +Signature: + +```typescript +send_to?: string | string[]; +``` diff --git a/docs-devsite/analytics.customparams.md b/docs-devsite/analytics.customparams.md new file mode 100644 index 00000000000..37ac6964477 --- /dev/null +++ b/docs-devsite/analytics.customparams.md @@ -0,0 +1,19 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# CustomParams interface +Any custom params the user may pass to `gtag`. + +Signature: + +```typescript +export interface CustomParams +``` diff --git a/docs-devsite/analytics.eventparams.md b/docs-devsite/analytics.eventparams.md new file mode 100644 index 00000000000..266b8d3e85e --- /dev/null +++ b/docs-devsite/analytics.eventparams.md @@ -0,0 +1,316 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# EventParams interface +Standard `gtag.js` event parameters. For more information, see [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export interface EventParams +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [affiliation](./analytics.eventparams.md#eventparamsaffiliation) | string | | +| [checkout\_option](./analytics.eventparams.md#eventparamscheckout_option) | string | | +| [checkout\_step](./analytics.eventparams.md#eventparamscheckout_step) | number | | +| [content\_type](./analytics.eventparams.md#eventparamscontent_type) | string | | +| [coupon](./analytics.eventparams.md#eventparamscoupon) | string | | +| [currency](./analytics.eventparams.md#eventparamscurrency) | string | | +| [description](./analytics.eventparams.md#eventparamsdescription) | string | | +| [event\_category](./analytics.eventparams.md#eventparamsevent_category) | string | | +| [event\_label](./analytics.eventparams.md#eventparamsevent_label) | string | | +| [fatal](./analytics.eventparams.md#eventparamsfatal) | boolean | | +| [firebase\_screen\_class](./analytics.eventparams.md#eventparamsfirebase_screen_class) | string | Firebase-specific. Use to log a screen_class to Firebase Analytics. | +| [firebase\_screen](./analytics.eventparams.md#eventparamsfirebase_screen) | string | Firebase-specific. Use to log a screen_name to Firebase Analytics. | +| [item\_id](./analytics.eventparams.md#eventparamsitem_id) | string | | +| [item\_list\_id](./analytics.eventparams.md#eventparamsitem_list_id) | string | | +| [item\_list\_name](./analytics.eventparams.md#eventparamsitem_list_name) | string | | +| [items](./analytics.eventparams.md#eventparamsitems) | [Item](./analytics.item.md#item_interface)\[\] | | +| [method](./analytics.eventparams.md#eventparamsmethod) | string | | +| [number](./analytics.eventparams.md#eventparamsnumber) | string | | +| [page\_location](./analytics.eventparams.md#eventparamspage_location) | string | | +| [page\_path](./analytics.eventparams.md#eventparamspage_path) | string | | +| [page\_title](./analytics.eventparams.md#eventparamspage_title) | string | | +| [payment\_type](./analytics.eventparams.md#eventparamspayment_type) | string | | +| [promotion\_id](./analytics.eventparams.md#eventparamspromotion_id) | string | | +| [promotion\_name](./analytics.eventparams.md#eventparamspromotion_name) | string | | +| [promotions](./analytics.eventparams.md#eventparamspromotions) | [Promotion](./analytics.promotion.md#promotion_interface)\[\] | | +| [screen\_name](./analytics.eventparams.md#eventparamsscreen_name) | string | | +| [search\_term](./analytics.eventparams.md#eventparamssearch_term) | string | | +| [shipping\_tier](./analytics.eventparams.md#eventparamsshipping_tier) | string | | +| [shipping](./analytics.eventparams.md#eventparamsshipping) | [Currency](./analytics.md#currency) | | +| [tax](./analytics.eventparams.md#eventparamstax) | [Currency](./analytics.md#currency) | | +| [transaction\_id](./analytics.eventparams.md#eventparamstransaction_id) | string | | +| [value](./analytics.eventparams.md#eventparamsvalue) | number | | + +## EventParams.affiliation + +Signature: + +```typescript +affiliation?: string; +``` + +## EventParams.checkout\_option + +Signature: + +```typescript +checkout_option?: string; +``` + +## EventParams.checkout\_step + +Signature: + +```typescript +checkout_step?: number; +``` + +## EventParams.content\_type + +Signature: + +```typescript +content_type?: string; +``` + +## EventParams.coupon + +Signature: + +```typescript +coupon?: string; +``` + +## EventParams.currency + +Signature: + +```typescript +currency?: string; +``` + +## EventParams.description + +Signature: + +```typescript +description?: string; +``` + +## EventParams.event\_category + +Signature: + +```typescript +event_category?: string; +``` + +## EventParams.event\_label + +Signature: + +```typescript +event_label?: string; +``` + +## EventParams.fatal + +Signature: + +```typescript +fatal?: boolean; +``` + +## EventParams.firebase\_screen\_class + +Firebase-specific. Use to log a `screen_class` to Firebase Analytics. + +Signature: + +```typescript +firebase_screen_class?: string; +``` + +## EventParams.firebase\_screen + +Firebase-specific. Use to log a `screen_name` to Firebase Analytics. + +Signature: + +```typescript +firebase_screen?: string; +``` + +## EventParams.item\_id + +Signature: + +```typescript +item_id?: string; +``` + +## EventParams.item\_list\_id + +Signature: + +```typescript +item_list_id?: string; +``` + +## EventParams.item\_list\_name + +Signature: + +```typescript +item_list_name?: string; +``` + +## EventParams.items + +Signature: + +```typescript +items?: Item[]; +``` + +## EventParams.method + +Signature: + +```typescript +method?: string; +``` + +## EventParams.number + +Signature: + +```typescript +number?: string; +``` + +## EventParams.page\_location + +Signature: + +```typescript +page_location?: string; +``` + +## EventParams.page\_path + +Signature: + +```typescript +page_path?: string; +``` + +## EventParams.page\_title + +Signature: + +```typescript +page_title?: string; +``` + +## EventParams.payment\_type + +Signature: + +```typescript +payment_type?: string; +``` + +## EventParams.promotion\_id + +Signature: + +```typescript +promotion_id?: string; +``` + +## EventParams.promotion\_name + +Signature: + +```typescript +promotion_name?: string; +``` + +## EventParams.promotions + +Signature: + +```typescript +promotions?: Promotion[]; +``` + +## EventParams.screen\_name + +Signature: + +```typescript +screen_name?: string; +``` + +## EventParams.search\_term + +Signature: + +```typescript +search_term?: string; +``` + +## EventParams.shipping\_tier + +Signature: + +```typescript +shipping_tier?: string; +``` + +## EventParams.shipping + +Signature: + +```typescript +shipping?: Currency; +``` + +## EventParams.tax + +Signature: + +```typescript +tax?: Currency; +``` + +## EventParams.transaction\_id + +Signature: + +```typescript +transaction_id?: string; +``` + +## EventParams.value + +Signature: + +```typescript +value?: number; +``` diff --git a/docs-devsite/analytics.gtagconfigparams.md b/docs-devsite/analytics.gtagconfigparams.md new file mode 100644 index 00000000000..f5138b8b65e --- /dev/null +++ b/docs-devsite/analytics.gtagconfigparams.md @@ -0,0 +1,134 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# GtagConfigParams interface +A set of common Google Analytics config settings recognized by `gtag.js`. + +Signature: + +```typescript +export interface GtagConfigParams +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [allow\_ad\_personalization\_signals](./analytics.gtagconfigparams.md#gtagconfigparamsallow_ad_personalization_signals) | boolean | If set to false, disables all advertising personalization with gtag.js. See [Disable advertising features](https://developers.google.com/analytics/devguides/collection/ga4/display-features) | +| [allow\_google\_signals](./analytics.gtagconfigparams.md#gtagconfigparamsallow_google_signals) | boolean | If set to false, disables all advertising features with gtag.js. See [Disable advertising features](https://developers.google.com/analytics/devguides/collection/ga4/display-features) | +| [cookie\_domain](./analytics.gtagconfigparams.md#gtagconfigparamscookie_domain) | string | Defaults to auto. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) | +| [cookie\_expires](./analytics.gtagconfigparams.md#gtagconfigparamscookie_expires) | number | Defaults to 63072000 (two years, in seconds). See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) | +| [cookie\_flags](./analytics.gtagconfigparams.md#gtagconfigparamscookie_flags) | string | Appends additional flags to the cookie when set. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) | +| [cookie\_prefix](./analytics.gtagconfigparams.md#gtagconfigparamscookie_prefix) | string | Defaults to _ga. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) | +| [cookie\_update](./analytics.gtagconfigparams.md#gtagconfigparamscookie_update) | boolean | If set to true, will update cookies on each page load. Defaults to true. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) | +| [page\_location](./analytics.gtagconfigparams.md#gtagconfigparamspage_location) | string | The URL of the page. See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view) | +| [page\_title](./analytics.gtagconfigparams.md#gtagconfigparamspage_title) | string | The title of the page. See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view) | +| [send\_page\_view](./analytics.gtagconfigparams.md#gtagconfigparamssend_page_view) | boolean | Whether or not a page view should be sent. If set to true (default), a page view is automatically sent upon initialization of analytics. See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view) | + +## GtagConfigParams.allow\_ad\_personalization\_signals + +If set to false, disables all advertising personalization with `gtag.js`. See [Disable advertising features](https://developers.google.com/analytics/devguides/collection/ga4/display-features) + +Signature: + +```typescript +'allow_ad_personalization_signals'?: boolean; +``` + +## GtagConfigParams.allow\_google\_signals + +If set to false, disables all advertising features with `gtag.js`. See [Disable advertising features](https://developers.google.com/analytics/devguides/collection/ga4/display-features) + +Signature: + +```typescript +'allow_google_signals'?: boolean; +``` + +## GtagConfigParams.cookie\_domain + +Defaults to `auto`. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) + +Signature: + +```typescript +'cookie_domain'?: string; +``` + +## GtagConfigParams.cookie\_expires + +Defaults to 63072000 (two years, in seconds). See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) + +Signature: + +```typescript +'cookie_expires'?: number; +``` + +## GtagConfigParams.cookie\_flags + +Appends additional flags to the cookie when set. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) + +Signature: + +```typescript +'cookie_flags'?: string; +``` + +## GtagConfigParams.cookie\_prefix + +Defaults to `_ga`. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) + +Signature: + +```typescript +'cookie_prefix'?: string; +``` + +## GtagConfigParams.cookie\_update + +If set to true, will update cookies on each page load. Defaults to true. See [Cookies and user identification](https://developers.google.com/analytics/devguides/collection/ga4/cookies-user-id) + +Signature: + +```typescript +'cookie_update'?: boolean; +``` + +## GtagConfigParams.page\_location + +The URL of the page. See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view) + +Signature: + +```typescript +'page_location'?: string; +``` + +## GtagConfigParams.page\_title + +The title of the page. See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view) + +Signature: + +```typescript +'page_title'?: string; +``` + +## GtagConfigParams.send\_page\_view + +Whether or not a page view should be sent. If set to true (default), a page view is automatically sent upon initialization of analytics. See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view) + +Signature: + +```typescript +'send_page_view'?: boolean; +``` diff --git a/docs-devsite/analytics.item.md b/docs-devsite/analytics.item.md new file mode 100644 index 00000000000..5c853918edb --- /dev/null +++ b/docs-devsite/analytics.item.md @@ -0,0 +1,278 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Item interface +Standard Google Analytics `Item` type. + +Signature: + +```typescript +export interface Item +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [affiliation](./analytics.item.md#itemaffiliation) | string | | +| [brand](./analytics.item.md#itembrand) | string | | +| [category](./analytics.item.md#itemcategory) | string | | +| [coupon](./analytics.item.md#itemcoupon) | string | | +| [creative\_name](./analytics.item.md#itemcreative_name) | string | | +| [creative\_slot](./analytics.item.md#itemcreative_slot) | string | | +| [discount](./analytics.item.md#itemdiscount) | [Currency](./analytics.md#currency) | | +| [id](./analytics.item.md#itemid) | string | | +| [index](./analytics.item.md#itemindex) | number | | +| [item\_brand](./analytics.item.md#itemitem_brand) | string | | +| [item\_category](./analytics.item.md#itemitem_category) | string | | +| [item\_category2](./analytics.item.md#itemitem_category2) | string | | +| [item\_category3](./analytics.item.md#itemitem_category3) | string | | +| [item\_category4](./analytics.item.md#itemitem_category4) | string | | +| [item\_category5](./analytics.item.md#itemitem_category5) | string | | +| [item\_id](./analytics.item.md#itemitem_id) | string | | +| [item\_list\_id](./analytics.item.md#itemitem_list_id) | string | | +| [item\_list\_name](./analytics.item.md#itemitem_list_name) | string | | +| [item\_name](./analytics.item.md#itemitem_name) | string | | +| [item\_variant](./analytics.item.md#itemitem_variant) | string | | +| [location\_id](./analytics.item.md#itemlocation_id) | string | | +| [name](./analytics.item.md#itemname) | string | | +| [price](./analytics.item.md#itemprice) | [Currency](./analytics.md#currency) | | +| [promotion\_id](./analytics.item.md#itempromotion_id) | string | | +| [promotion\_name](./analytics.item.md#itempromotion_name) | string | | +| [quantity](./analytics.item.md#itemquantity) | number | | + +## Item.affiliation + +Signature: + +```typescript +affiliation?: string; +``` + +## Item.brand + +> Warning: This API is now obsolete. +> +> Use item\_brand instead. +> + +Signature: + +```typescript +brand?: string; +``` + +## Item.category + +> Warning: This API is now obsolete. +> +> Use item\_category instead. +> + +Signature: + +```typescript +category?: string; +``` + +## Item.coupon + +Signature: + +```typescript +coupon?: string; +``` + +## Item.creative\_name + +Signature: + +```typescript +creative_name?: string; +``` + +## Item.creative\_slot + +Signature: + +```typescript +creative_slot?: string; +``` + +## Item.discount + +Signature: + +```typescript +discount?: Currency; +``` + +## Item.id + +> Warning: This API is now obsolete. +> +> Use item\_id instead. +> + +Signature: + +```typescript +id?: string; +``` + +## Item.index + +Signature: + +```typescript +index?: number; +``` + +## Item.item\_brand + +Signature: + +```typescript +item_brand?: string; +``` + +## Item.item\_category + +Signature: + +```typescript +item_category?: string; +``` + +## Item.item\_category2 + +Signature: + +```typescript +item_category2?: string; +``` + +## Item.item\_category3 + +Signature: + +```typescript +item_category3?: string; +``` + +## Item.item\_category4 + +Signature: + +```typescript +item_category4?: string; +``` + +## Item.item\_category5 + +Signature: + +```typescript +item_category5?: string; +``` + +## Item.item\_id + +Signature: + +```typescript +item_id?: string; +``` + +## Item.item\_list\_id + +Signature: + +```typescript +item_list_id?: string; +``` + +## Item.item\_list\_name + +Signature: + +```typescript +item_list_name?: string; +``` + +## Item.item\_name + +Signature: + +```typescript +item_name?: string; +``` + +## Item.item\_variant + +Signature: + +```typescript +item_variant?: string; +``` + +## Item.location\_id + +Signature: + +```typescript +location_id?: string; +``` + +## Item.name + +> Warning: This API is now obsolete. +> +> Use item\_name instead. +> + +Signature: + +```typescript +name?: string; +``` + +## Item.price + +Signature: + +```typescript +price?: Currency; +``` + +## Item.promotion\_id + +Signature: + +```typescript +promotion_id?: string; +``` + +## Item.promotion\_name + +Signature: + +```typescript +promotion_name?: string; +``` + +## Item.quantity + +Signature: + +```typescript +quantity?: number; +``` diff --git a/docs-devsite/analytics.md b/docs-devsite/analytics.md new file mode 100644 index 00000000000..bd6e4b69351 --- /dev/null +++ b/docs-devsite/analytics.md @@ -0,0 +1,991 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# analytics package +Firebase Analytics + +## Functions + +| Function | Description | +| --- | --- | +| function(app...) | +| [getAnalytics(app)](./analytics.md#getanalytics) | Returns an [Analytics](./analytics.analytics.md#analytics_interface) instance for the given app. | +| [initializeAnalytics(app, options)](./analytics.md#initializeanalytics) | Returns an [Analytics](./analytics.analytics.md#analytics_interface) instance for the given app. | +| function(analyticsInstance...) | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.See [Track Screenviews](https://firebase.google.com/docs/analytics/screenviews). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.See [Measure exceptions](https://developers.google.com/analytics/devguides/collection/ga4/exceptions). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given eventParams. This method automatically associates this logged event with this Firebase web app instance on this device.See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view). | +| [setAnalyticsCollectionEnabled(analyticsInstance, enabled)](./analytics.md#setanalyticscollectionenabled) | Sets whether Google Analytics collection is enabled for this app on this device. Sets global window['ga-disable-analyticsId'] = true; | +| [setCurrentScreen(analyticsInstance, screenName, options)](./analytics.md#setcurrentscreen) | Use gtag config command to set screen_name. | +| [setUserId(analyticsInstance, id, options)](./analytics.md#setuserid) | Use gtag config command to set user_id. | +| [setUserProperties(analyticsInstance, properties, options)](./analytics.md#setuserproperties) | Use gtag config command to set all params specified. | +| function() | +| [isSupported()](./analytics.md#issupported) | This is a public static method provided to users that wraps four different checks:1. Check if it's not a browser extension environment. 2. Check if cookies are enabled in current browser. 3. Check if IndexedDB is supported by the browser environment. 4. Check if the current browser context is valid for using IndexedDB.open(). | +| function(consentSettings...) | +| [setConsent(consentSettings)](./analytics.md#setconsent) | Sets the applicable end user consent state for this web app across all gtag references once Firebase Analytics is initialized.Use the [ConsentSettings](./analytics.consentsettings.md#consentsettings_interface) to specify individual consent type values. By default consent types are set to "granted". | +| function(customParams...) | +| [setDefaultEventParameters(customParams)](./analytics.md#setdefaulteventparameters) | Adds data that will be set on every event logged from the SDK, including automatic ones. With gtag's "set" command, the values passed persist on the current page and are passed with all subsequent events. | +| function(options...) | +| [settings(options)](./analytics.md#settings) | Configures Firebase Analytics to use custom gtag or dataLayer names. Intended to be used if gtag.js script has been installed on this page independently of Firebase Analytics, and is using non-default names for either the gtag function or for dataLayer. Must be called before calling getAnalytics() or it won't have any effect. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [Analytics](./analytics.analytics.md#analytics_interface) | An instance of Firebase Analytics. | +| [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | Additional options that can be passed to Analytics method calls such as logEvent, etc. | +| [AnalyticsSettings](./analytics.analyticssettings.md#analyticssettings_interface) | [Analytics](./analytics.analytics.md#analytics_interface) instance initialization options. | +| [ConsentSettings](./analytics.consentsettings.md#consentsettings_interface) | Consent status settings for each consent type. For more information, see [the GA4 reference documentation for consent state and consent types](https://developers.google.com/tag-platform/tag-manager/templates/consent-apis). | +| [ControlParams](./analytics.controlparams.md#controlparams_interface) | Standard gtag.js control parameters. For more information, see [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [CustomParams](./analytics.customparams.md#customparams_interface) | Any custom params the user may pass to gtag. | +| [EventParams](./analytics.eventparams.md#eventparams_interface) | Standard gtag.js event parameters. For more information, see [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). | +| [GtagConfigParams](./analytics.gtagconfigparams.md#gtagconfigparams_interface) | A set of common Google Analytics config settings recognized by gtag.js. | +| [Item](./analytics.item.md#item_interface) | Standard Google Analytics Item type. | +| [Promotion](./analytics.promotion.md#promotion_interface) | Field previously used by some Google Analytics events. | +| [SettingsOptions](./analytics.settingsoptions.md#settingsoptions_interface) | Specifies custom options for your Firebase Analytics instance. You must set these before initializing firebase.analytics(). | + +## Type Aliases + +| Type Alias | Description | +| --- | --- | +| [ConsentStatusString](./analytics.md#consentstatusstring) | Whether a particular consent type has been granted or denied. | +| [Currency](./analytics.md#currency) | Standard Google Analytics currency type. | +| [CustomEventName](./analytics.md#customeventname) | Any custom event name string not in the standard list of recommended event names. | +| [EventNameString](./analytics.md#eventnamestring) | Type for standard Google Analytics event names. logEvent also accepts any custom string and interprets it as a custom event name. | + +## getAnalytics() + +Returns an [Analytics](./analytics.analytics.md#analytics_interface) instance for the given app. + +Signature: + +```typescript +export declare function getAnalytics(app?: FirebaseApp): Analytics; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to use. | + +Returns: + +[Analytics](./analytics.analytics.md#analytics_interface) + +## initializeAnalytics() + +Returns an [Analytics](./analytics.analytics.md#analytics_interface) instance for the given app. + +Signature: + +```typescript +export declare function initializeAnalytics(app: FirebaseApp, options?: AnalyticsSettings): Analytics; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to use. | +| options | [AnalyticsSettings](./analytics.analyticssettings.md#analyticssettings_interface) | | + +Returns: + +[Analytics](./analytics.analytics.md#analytics_interface) + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'add_payment_info', eventParams?: { + coupon?: EventParams['coupon']; + currency?: EventParams['currency']; + items?: EventParams['items']; + payment_type?: EventParams['payment_type']; + value?: EventParams['value']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'add\_payment\_info' | | +| eventParams | { coupon?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['coupon'\]; currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; payment\_type?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['payment\_type'\]; value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'purchase' | 'refund', eventParams?: { + value?: EventParams['value']; + currency?: EventParams['currency']; + transaction_id: EventParams['transaction_id']; + tax?: EventParams['tax']; + shipping?: EventParams['shipping']; + items?: EventParams['items']; + coupon?: EventParams['coupon']; + affiliation?: EventParams['affiliation']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'purchase' \| 'refund' | | +| eventParams | { value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; transaction\_id: [EventParams](./analytics.eventparams.md#eventparams_interface)\['transaction\_id'\]; tax?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['tax'\]; shipping?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['shipping'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; coupon?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['coupon'\]; affiliation?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['affiliation'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +See [Track Screenviews](https://firebase.google.com/docs/analytics/screenviews). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'screen_view', eventParams?: { + firebase_screen: EventParams['firebase_screen']; + firebase_screen_class: EventParams['firebase_screen_class']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'screen\_view' | | +| eventParams | { firebase\_screen: [EventParams](./analytics.eventparams.md#eventparams_interface)\['firebase\_screen'\]; firebase\_screen\_class: [EventParams](./analytics.eventparams.md#eventparams_interface)\['firebase\_screen\_class'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'search' | 'view_search_results', eventParams?: { + search_term?: EventParams['search_term']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'search' \| 'view\_search\_results' | | +| eventParams | { search\_term?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['search\_term'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'select_content', eventParams?: { + content_type?: EventParams['content_type']; + item_id?: EventParams['item_id']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'select\_content' | | +| eventParams | { content\_type?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['content\_type'\]; item\_id?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['item\_id'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'select_item', eventParams?: { + items?: EventParams['items']; + item_list_name?: EventParams['item_list_name']; + item_list_id?: EventParams['item_list_id']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'select\_item' | | +| eventParams | { items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; item\_list\_name?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['item\_list\_name'\]; item\_list\_id?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['item\_list\_id'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'select_promotion' | 'view_promotion', eventParams?: { + items?: EventParams['items']; + promotion_id?: EventParams['promotion_id']; + promotion_name?: EventParams['promotion_name']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'select\_promotion' \| 'view\_promotion' | | +| eventParams | { items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; promotion\_id?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['promotion\_id'\]; promotion\_name?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['promotion\_name'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'set_checkout_option', eventParams?: { + checkout_step?: EventParams['checkout_step']; + checkout_option?: EventParams['checkout_option']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'set\_checkout\_option' | | +| eventParams | { checkout\_step?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['checkout\_step'\]; checkout\_option?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['checkout\_option'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'share', eventParams?: { + method?: EventParams['method']; + content_type?: EventParams['content_type']; + item_id?: EventParams['item_id']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'share' | | +| eventParams | { method?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['method'\]; content\_type?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['content\_type'\]; item\_id?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['item\_id'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'sign_up', eventParams?: { + method?: EventParams['method']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'sign\_up' | | +| eventParams | { method?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['method'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'timing_complete', eventParams?: { + name: string; + value: number; + event_category?: string; + event_label?: string; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'timing\_complete' | | +| eventParams | { name: string; value: number; event\_category?: string; event\_label?: string; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'add_shipping_info', eventParams?: { + coupon?: EventParams['coupon']; + currency?: EventParams['currency']; + items?: EventParams['items']; + shipping_tier?: EventParams['shipping_tier']; + value?: EventParams['value']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'add\_shipping\_info' | | +| eventParams | { coupon?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['coupon'\]; currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; shipping\_tier?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['shipping\_tier'\]; value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'view_cart' | 'view_item', eventParams?: { + currency?: EventParams['currency']; + items?: EventParams['items']; + value?: EventParams['value']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'view\_cart' \| 'view\_item' | | +| eventParams | { currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'view_item_list', eventParams?: { + items?: EventParams['items']; + item_list_name?: EventParams['item_list_name']; + item_list_id?: EventParams['item_list_id']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'view\_item\_list' | | +| eventParams | { items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; item\_list\_name?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['item\_list\_name'\]; item\_list\_id?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['item\_list\_id'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: CustomEventName, eventParams?: { + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | [CustomEventName](./analytics.md#customeventname)<T> | | +| eventParams | { \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'add_to_cart' | 'add_to_wishlist' | 'remove_from_cart', eventParams?: { + currency?: EventParams['currency']; + value?: EventParams['value']; + items?: EventParams['items']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'add\_to\_cart' \| 'add\_to\_wishlist' \| 'remove\_from\_cart' | | +| eventParams | { currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'begin_checkout', eventParams?: { + currency?: EventParams['currency']; + coupon?: EventParams['coupon']; + value?: EventParams['value']; + items?: EventParams['items']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'begin\_checkout' | | +| eventParams | { currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; coupon?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['coupon'\]; value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'checkout_progress', eventParams?: { + currency?: EventParams['currency']; + coupon?: EventParams['coupon']; + value?: EventParams['value']; + items?: EventParams['items']; + checkout_step?: EventParams['checkout_step']; + checkout_option?: EventParams['checkout_option']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'checkout\_progress' | | +| eventParams | { currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; coupon?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['coupon'\]; value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; items?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['items'\]; checkout\_step?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['checkout\_step'\]; checkout\_option?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['checkout\_option'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +See [Measure exceptions](https://developers.google.com/analytics/devguides/collection/ga4/exceptions). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'exception', eventParams?: { + description?: EventParams['description']; + fatal?: EventParams['fatal']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'exception' | | +| eventParams | { description?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['description'\]; fatal?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['fatal'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'generate_lead', eventParams?: { + value?: EventParams['value']; + currency?: EventParams['currency']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'generate\_lead' | | +| eventParams | { value?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['value'\]; currency?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['currency'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'login', eventParams?: { + method?: EventParams['method']; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'login' | | +| eventParams | { method?: [EventParams](./analytics.eventparams.md#eventparams_interface)\['method'\]; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## logEvent() + +Sends a Google Analytics event with given `eventParams`. This method automatically associates this logged event with this Firebase web app instance on this device. + +See [Page views](https://developers.google.com/analytics/devguides/collection/ga4/page-view). + +Signature: + +```typescript +export declare function logEvent(analyticsInstance: Analytics, eventName: 'page_view', eventParams?: { + page_title?: string; + page_location?: string; + page_path?: string; + [key: string]: any; +}, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| eventName | 'page\_view' | | +| eventParams | { page\_title?: string; page\_location?: string; page\_path?: string; \[key: string\]: any; } | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## setAnalyticsCollectionEnabled() + +Sets whether Google Analytics collection is enabled for this app on this device. Sets global `window['ga-disable-analyticsId'] = true;` + +Signature: + +```typescript +export declare function setAnalyticsCollectionEnabled(analyticsInstance: Analytics, enabled: boolean): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | The [Analytics](./analytics.analytics.md#analytics_interface) instance. | +| enabled | boolean | If true, enables collection, if false, disables it. | + +Returns: + +void + +## setCurrentScreen() + +> Warning: This API is now obsolete. +> +> Use with `eventName` as 'screen\_view' and add relevant `eventParams`. See [Track Screenviews](https://firebase.google.com/docs/analytics/screenviews). +> + +Use gtag `config` command to set `screen_name`. + +Signature: + +```typescript +export declare function setCurrentScreen(analyticsInstance: Analytics, screenName: string, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | The [Analytics](./analytics.analytics.md#analytics_interface) instance. | +| screenName | string | Screen name to set. | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## setUserId() + +Use gtag `config` command to set `user_id`. + +Signature: + +```typescript +export declare function setUserId(analyticsInstance: Analytics, id: string | null, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | The [Analytics](./analytics.analytics.md#analytics_interface) instance. | +| id | string \| null | User ID to set. | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## setUserProperties() + +Use gtag `config` command to set all params specified. + +Signature: + +```typescript +export declare function setUserProperties(analyticsInstance: Analytics, properties: CustomParams, options?: AnalyticsCallOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) | | +| properties | [CustomParams](./analytics.customparams.md#customparams_interface) | | +| options | [AnalyticsCallOptions](./analytics.analyticscalloptions.md#analyticscalloptions_interface) | | + +Returns: + +void + +## isSupported() + +This is a public static method provided to users that wraps four different checks: + +1. Check if it's not a browser extension environment. 2. Check if cookies are enabled in current browser. 3. Check if IndexedDB is supported by the browser environment. 4. Check if the current browser context is valid for using `IndexedDB.open()`. + +Signature: + +```typescript +export declare function isSupported(): Promise; +``` +Returns: + +Promise<boolean> + +## setConsent() + +Sets the applicable end user consent state for this web app across all gtag references once Firebase Analytics is initialized. + +Use the [ConsentSettings](./analytics.consentsettings.md#consentsettings_interface) to specify individual consent type values. By default consent types are set to "granted". + +Signature: + +```typescript +export declare function setConsent(consentSettings: ConsentSettings): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| consentSettings | [ConsentSettings](./analytics.consentsettings.md#consentsettings_interface) | Maps the applicable end user consent state for gtag.js. | + +Returns: + +void + +## setDefaultEventParameters() + +Adds data that will be set on every event logged from the SDK, including automatic ones. With gtag's "set" command, the values passed persist on the current page and are passed with all subsequent events. + +Signature: + +```typescript +export declare function setDefaultEventParameters(customParams: CustomParams): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| customParams | [CustomParams](./analytics.customparams.md#customparams_interface) | Any custom params the user may pass to gtag.js. | + +Returns: + +void + +## settings() + +Configures Firebase Analytics to use custom `gtag` or `dataLayer` names. Intended to be used if `gtag.js` script has been installed on this page independently of Firebase Analytics, and is using non-default names for either the `gtag` function or for `dataLayer`. Must be called before calling `getAnalytics()` or it won't have any effect. + +Signature: + +```typescript +export declare function settings(options: SettingsOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| options | [SettingsOptions](./analytics.settingsoptions.md#settingsoptions_interface) | Custom gtag and dataLayer names. | + +Returns: + +void + +## ConsentStatusString + +Whether a particular consent type has been granted or denied. + +Signature: + +```typescript +export declare type ConsentStatusString = 'granted' | 'denied'; +``` + +## Currency + +Standard Google Analytics currency type. + +Signature: + +```typescript +export declare type Currency = string | number; +``` + +## CustomEventName + +Any custom event name string not in the standard list of recommended event names. + +Signature: + +```typescript +export declare type CustomEventName = T extends EventNameString ? never : T; +``` + +## EventNameString + +Type for standard Google Analytics event names. `logEvent` also accepts any custom string and interprets it as a custom event name. + +Signature: + +```typescript +export declare type EventNameString = 'add_payment_info' | 'add_shipping_info' | 'add_to_cart' | 'add_to_wishlist' | 'begin_checkout' | 'checkout_progress' | 'exception' | 'generate_lead' | 'login' | 'page_view' | 'purchase' | 'refund' | 'remove_from_cart' | 'screen_view' | 'search' | 'select_content' | 'select_item' | 'select_promotion' | 'set_checkout_option' | 'share' | 'sign_up' | 'timing_complete' | 'view_cart' | 'view_item' | 'view_item_list' | 'view_promotion' | 'view_search_results'; +``` diff --git a/docs-devsite/analytics.promotion.md b/docs-devsite/analytics.promotion.md new file mode 100644 index 00000000000..7e29e0335e4 --- /dev/null +++ b/docs-devsite/analytics.promotion.md @@ -0,0 +1,65 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Promotion interface +> Warning: This API is now obsolete. +> +> Use `Item` instead. +> + +Field previously used by some Google Analytics events. + +Signature: + +```typescript +export interface Promotion +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [creative\_name](./analytics.promotion.md#promotioncreative_name) | string | | +| [creative\_slot](./analytics.promotion.md#promotioncreative_slot) | string | | +| [id](./analytics.promotion.md#promotionid) | string | | +| [name](./analytics.promotion.md#promotionname) | string | | + +## Promotion.creative\_name + +Signature: + +```typescript +creative_name?: string; +``` + +## Promotion.creative\_slot + +Signature: + +```typescript +creative_slot?: string; +``` + +## Promotion.id + +Signature: + +```typescript +id?: string; +``` + +## Promotion.name + +Signature: + +```typescript +name?: string; +``` diff --git a/docs-devsite/analytics.settingsoptions.md b/docs-devsite/analytics.settingsoptions.md new file mode 100644 index 00000000000..e43152074d0 --- /dev/null +++ b/docs-devsite/analytics.settingsoptions.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# SettingsOptions interface +Specifies custom options for your Firebase Analytics instance. You must set these before initializing `firebase.analytics()`. + +Signature: + +```typescript +export interface SettingsOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [dataLayerName](./analytics.settingsoptions.md#settingsoptionsdatalayername) | string | Sets custom name for dataLayer array used by gtag.js. | +| [gtagName](./analytics.settingsoptions.md#settingsoptionsgtagname) | string | Sets custom name for gtag function. | + +## SettingsOptions.dataLayerName + +Sets custom name for `dataLayer` array used by `gtag.js`. + +Signature: + +```typescript +dataLayerName?: string; +``` + +## SettingsOptions.gtagName + +Sets custom name for `gtag` function. + +Signature: + +```typescript +gtagName?: string; +``` diff --git a/docs-devsite/app-check.appcheck.md b/docs-devsite/app-check.appcheck.md new file mode 100644 index 00000000000..a4cb809924d --- /dev/null +++ b/docs-devsite/app-check.appcheck.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AppCheck interface +The Firebase App Check service interface. + +Signature: + +```typescript +export interface AppCheck +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [app](./app-check.appcheck.md#appcheckapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this AppCheck instance is associated with. | + +## AppCheck.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `AppCheck` instance is associated with. + +Signature: + +```typescript +app: FirebaseApp; +``` diff --git a/docs-devsite/app-check.appcheckoptions.md b/docs-devsite/app-check.appcheckoptions.md new file mode 100644 index 00000000000..4d3630faa65 --- /dev/null +++ b/docs-devsite/app-check.appcheckoptions.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AppCheckOptions interface +Options for App Check initialization. + +Signature: + +```typescript +export interface AppCheckOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [isTokenAutoRefreshEnabled](./app-check.appcheckoptions.md#appcheckoptionsistokenautorefreshenabled) | boolean | If set to true, enables automatic background refresh of App Check token. | +| [provider](./app-check.appcheckoptions.md#appcheckoptionsprovider) | [CustomProvider](./app-check.customprovider.md#customprovider_class) \| [ReCaptchaV3Provider](./app-check.recaptchav3provider.md#recaptchav3provider_class) \| [ReCaptchaEnterpriseProvider](./app-check.recaptchaenterpriseprovider.md#recaptchaenterpriseprovider_class) | A reCAPTCHA V3 provider, reCAPTCHA Enterprise provider, or custom provider. | + +## AppCheckOptions.isTokenAutoRefreshEnabled + +If set to true, enables automatic background refresh of App Check token. + +Signature: + +```typescript +isTokenAutoRefreshEnabled?: boolean; +``` + +## AppCheckOptions.provider + +A reCAPTCHA V3 provider, reCAPTCHA Enterprise provider, or custom provider. + +Signature: + +```typescript +provider: CustomProvider | ReCaptchaV3Provider | ReCaptchaEnterpriseProvider; +``` diff --git a/docs-devsite/app-check.appchecktoken.md b/docs-devsite/app-check.appchecktoken.md new file mode 100644 index 00000000000..9cb71d78bbb --- /dev/null +++ b/docs-devsite/app-check.appchecktoken.md @@ -0,0 +1,44 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AppCheckToken interface +The token returned from an App Check provider. + +Signature: + +```typescript +export interface AppCheckToken +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [expireTimeMillis](./app-check.appchecktoken.md#appchecktokenexpiretimemillis) | number | The local timestamp after which the token will expire. | +| [token](./app-check.appchecktoken.md#appchecktokentoken) | string | | + +## AppCheckToken.expireTimeMillis + +The local timestamp after which the token will expire. + +Signature: + +```typescript +readonly expireTimeMillis: number; +``` + +## AppCheckToken.token + +Signature: + +```typescript +readonly token: string; +``` diff --git a/docs-devsite/app-check.appchecktokenresult.md b/docs-devsite/app-check.appchecktokenresult.md new file mode 100644 index 00000000000..185d60992c1 --- /dev/null +++ b/docs-devsite/app-check.appchecktokenresult.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AppCheckTokenResult interface +Result returned by `getToken()`. + +Signature: + +```typescript +export interface AppCheckTokenResult +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [token](./app-check.appchecktokenresult.md#appchecktokenresulttoken) | string | The token string in JWT format. | + +## AppCheckTokenResult.token + +The token string in JWT format. + +Signature: + +```typescript +readonly token: string; +``` diff --git a/docs-devsite/app-check.customprovider.md b/docs-devsite/app-check.customprovider.md new file mode 100644 index 00000000000..e00da1d7897 --- /dev/null +++ b/docs-devsite/app-check.customprovider.md @@ -0,0 +1,43 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# CustomProvider class +Custom provider class. + +Signature: + +```typescript +export declare class CustomProvider implements AppCheckProvider +``` +Implements: AppCheckProvider + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(\_customProviderOptions)](./app-check.customprovider.md#customproviderconstructor) | | Constructs a new instance of the CustomProvider class | + +## CustomProvider.(constructor) + +Constructs a new instance of the `CustomProvider` class + +Signature: + +```typescript +constructor(_customProviderOptions: CustomProviderOptions); +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| \_customProviderOptions | [CustomProviderOptions](./app-check.customprovideroptions.md#customprovideroptions_interface) | | + diff --git a/docs-devsite/app-check.customprovideroptions.md b/docs-devsite/app-check.customprovideroptions.md new file mode 100644 index 00000000000..c122e0476dd --- /dev/null +++ b/docs-devsite/app-check.customprovideroptions.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# CustomProviderOptions interface +Options when creating a [CustomProvider](./app-check.customprovider.md#customprovider_class). + +Signature: + +```typescript +export interface CustomProviderOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [getToken](./app-check.customprovideroptions.md#customprovideroptionsgettoken) | () => Promise<[AppCheckToken](./app-check.appchecktoken.md#appchecktoken_interface)> | Function to get an App Check token through a custom provider service. | + +## CustomProviderOptions.getToken + +Function to get an App Check token through a custom provider service. + +Signature: + +```typescript +getToken: () => Promise; +``` diff --git a/docs-devsite/app-check.md b/docs-devsite/app-check.md new file mode 100644 index 00000000000..b7895a05c96 --- /dev/null +++ b/docs-devsite/app-check.md @@ -0,0 +1,170 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# app-check package +Firebase App Check + +## Functions + +| Function | Description | +| --- | --- | +| function(app...) | +| [initializeAppCheck(app, options)](./app-check.md#initializeappcheck) | Activate App Check for the given app. Can be called only once per app. | +| function(appCheckInstance...) | +| [getToken(appCheckInstance, forceRefresh)](./app-check.md#gettoken) | Get the current App Check token. Attaches to the most recent in-flight request if one is present. Returns null if no token is present and no token requests are in-flight. | +| [onTokenChanged(appCheckInstance, observer)](./app-check.md#ontokenchanged) | Registers a listener to changes in the token state. There can be more than one listener registered at the same time for one or more App Check instances. The listeners call back on the UI thread whenever the current token associated with this App Check instance changes. | +| [onTokenChanged(appCheckInstance, onNext, onError, onCompletion)](./app-check.md#ontokenchanged) | Registers a listener to changes in the token state. There can be more than one listener registered at the same time for one or more App Check instances. The listeners call back on the UI thread whenever the current token associated with this App Check instance changes. | +| [setTokenAutoRefreshEnabled(appCheckInstance, isTokenAutoRefreshEnabled)](./app-check.md#settokenautorefreshenabled) | Set whether App Check will automatically refresh tokens as needed. | + +## Classes + +| Class | Description | +| --- | --- | +| [CustomProvider](./app-check.customprovider.md#customprovider_class) | Custom provider class. | +| [ReCaptchaEnterpriseProvider](./app-check.recaptchaenterpriseprovider.md#recaptchaenterpriseprovider_class) | App Check provider that can obtain a reCAPTCHA Enterprise token and exchange it for an App Check token. | +| [ReCaptchaV3Provider](./app-check.recaptchav3provider.md#recaptchav3provider_class) | App Check provider that can obtain a reCAPTCHA V3 token and exchange it for an App Check token. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [AppCheck](./app-check.appcheck.md#appcheck_interface) | The Firebase App Check service interface. | +| [AppCheckOptions](./app-check.appcheckoptions.md#appcheckoptions_interface) | Options for App Check initialization. | +| [AppCheckToken](./app-check.appchecktoken.md#appchecktoken_interface) | The token returned from an App Check provider. | +| [AppCheckTokenResult](./app-check.appchecktokenresult.md#appchecktokenresult_interface) | Result returned by getToken(). | +| [CustomProviderOptions](./app-check.customprovideroptions.md#customprovideroptions_interface) | Options when creating a [CustomProvider](./app-check.customprovider.md#customprovider_class). | + +## Type Aliases + +| Type Alias | Description | +| --- | --- | +| [AppCheckTokenListener](./app-check.md#appchecktokenlistener) | A listener that is called whenever the App Check token changes. | + +## initializeAppCheck() + +Activate App Check for the given app. Can be called only once per app. + +Signature: + +```typescript +export declare function initializeAppCheck(app: FirebaseApp | undefined, options: AppCheckOptions): AppCheck; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) \| undefined | the [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to activate App Check for | +| options | [AppCheckOptions](./app-check.appcheckoptions.md#appcheckoptions_interface) | App Check initialization options | + +Returns: + +[AppCheck](./app-check.appcheck.md#appcheck_interface) + +## getToken() + +Get the current App Check token. Attaches to the most recent in-flight request if one is present. Returns null if no token is present and no token requests are in-flight. + +Signature: + +```typescript +export declare function getToken(appCheckInstance: AppCheck, forceRefresh?: boolean): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| appCheckInstance | [AppCheck](./app-check.appcheck.md#appcheck_interface) | The App Check service instance. | +| forceRefresh | boolean | If true, will always try to fetch a fresh token. If false, will use a cached token if found in storage. | + +Returns: + +Promise<[AppCheckTokenResult](./app-check.appchecktokenresult.md#appchecktokenresult_interface)> + +## onTokenChanged() + +Registers a listener to changes in the token state. There can be more than one listener registered at the same time for one or more App Check instances. The listeners call back on the UI thread whenever the current token associated with this App Check instance changes. + +Signature: + +```typescript +export declare function onTokenChanged(appCheckInstance: AppCheck, observer: PartialObserver): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| appCheckInstance | [AppCheck](./app-check.appcheck.md#appcheck_interface) | The App Check service instance. | +| observer | [PartialObserver](./util.md#partialobserver)<[AppCheckTokenResult](./app-check.appchecktokenresult.md#appchecktokenresult_interface)> | An object with next, error, and complete properties. next is called with an [AppCheckTokenResult](./app-check.appchecktokenresult.md#appchecktokenresult_interface) whenever the token changes. error is optional and is called if an error is thrown by the listener (the next function). complete is unused, as the token stream is unending. | + +Returns: + +[Unsubscribe](./util.md#unsubscribe) + +A function that unsubscribes this listener. + +## onTokenChanged() + +Registers a listener to changes in the token state. There can be more than one listener registered at the same time for one or more App Check instances. The listeners call back on the UI thread whenever the current token associated with this App Check instance changes. + +Signature: + +```typescript +export declare function onTokenChanged(appCheckInstance: AppCheck, onNext: (tokenResult: AppCheckTokenResult) => void, onError?: (error: Error) => void, onCompletion?: () => void): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| appCheckInstance | [AppCheck](./app-check.appcheck.md#appcheck_interface) | The App Check service instance. | +| onNext | (tokenResult: [AppCheckTokenResult](./app-check.appchecktokenresult.md#appchecktokenresult_interface)) => void | When the token changes, this function is called with aa [AppCheckTokenResult](./app-check.appchecktokenresult.md#appchecktokenresult_interface). | +| onError | (error: Error) => void | Optional. Called if there is an error thrown by the listener (the onNext function). | +| onCompletion | () => void | Currently unused, as the token stream is unending. | + +Returns: + +[Unsubscribe](./util.md#unsubscribe) + +A function that unsubscribes this listener. + +## setTokenAutoRefreshEnabled() + +Set whether App Check will automatically refresh tokens as needed. + +Signature: + +```typescript +export declare function setTokenAutoRefreshEnabled(appCheckInstance: AppCheck, isTokenAutoRefreshEnabled: boolean): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| appCheckInstance | [AppCheck](./app-check.appcheck.md#appcheck_interface) | The App Check service instance. | +| isTokenAutoRefreshEnabled | boolean | If true, the SDK automatically refreshes App Check tokens as needed. This overrides any value set during initializeAppCheck(). | + +Returns: + +void + +## AppCheckTokenListener + +A listener that is called whenever the App Check token changes. + +Signature: + +```typescript +export declare type AppCheckTokenListener = (token: AppCheckTokenResult) => void; +``` diff --git a/docs-devsite/app-check.recaptchaenterpriseprovider.md b/docs-devsite/app-check.recaptchaenterpriseprovider.md new file mode 100644 index 00000000000..21222c24fb9 --- /dev/null +++ b/docs-devsite/app-check.recaptchaenterpriseprovider.md @@ -0,0 +1,43 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ReCaptchaEnterpriseProvider class +App Check provider that can obtain a reCAPTCHA Enterprise token and exchange it for an App Check token. + +Signature: + +```typescript +export declare class ReCaptchaEnterpriseProvider implements AppCheckProvider +``` +Implements: AppCheckProvider + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(\_siteKey)](./app-check.recaptchaenterpriseprovider.md#recaptchaenterpriseproviderconstructor) | | Create a ReCaptchaEnterpriseProvider instance. | + +## ReCaptchaEnterpriseProvider.(constructor) + +Create a ReCaptchaEnterpriseProvider instance. + +Signature: + +```typescript +constructor(_siteKey: string); +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| \_siteKey | string | | + diff --git a/docs-devsite/app-check.recaptchav3provider.md b/docs-devsite/app-check.recaptchav3provider.md new file mode 100644 index 00000000000..f2df61a639d --- /dev/null +++ b/docs-devsite/app-check.recaptchav3provider.md @@ -0,0 +1,43 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ReCaptchaV3Provider class +App Check provider that can obtain a reCAPTCHA V3 token and exchange it for an App Check token. + +Signature: + +```typescript +export declare class ReCaptchaV3Provider implements AppCheckProvider +``` +Implements: AppCheckProvider + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(\_siteKey)](./app-check.recaptchav3provider.md#recaptchav3providerconstructor) | | Create a ReCaptchaV3Provider instance. | + +## ReCaptchaV3Provider.(constructor) + +Create a ReCaptchaV3Provider instance. + +Signature: + +```typescript +constructor(_siteKey: string); +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| \_siteKey | string | | + diff --git a/docs-devsite/app.firebaseapp.md b/docs-devsite/app.firebaseapp.md new file mode 100644 index 00000000000..cafbfdd7c54 --- /dev/null +++ b/docs-devsite/app.firebaseapp.md @@ -0,0 +1,91 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FirebaseApp interface +A [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) holds the initialization information for a collection of services. + +Do not call this constructor directly. Instead, use [initializeApp()](./app.md#initializeapp) to create an app. + +Signature: + +```typescript +export interface FirebaseApp +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [automaticDataCollectionEnabled](./app.firebaseapp.md#firebaseappautomaticdatacollectionenabled) | boolean | The settable config flag for GDPR opt-in/opt-out | +| [name](./app.firebaseapp.md#firebaseappname) | string | The (read-only) name for this app.The default app's name is "[DEFAULT]". | +| [options](./app.firebaseapp.md#firebaseappoptions) | [FirebaseOptions](./app.firebaseoptions.md#firebaseoptions_interface) | The (read-only) configuration options for this app. These are the original parameters given in [initializeApp()](./app.md#initializeapp). | + +## FirebaseApp.automaticDataCollectionEnabled + +The settable config flag for GDPR opt-in/opt-out + +Signature: + +```typescript +automaticDataCollectionEnabled: boolean; +``` + +## FirebaseApp.name + +The (read-only) name for this app. + +The default app's name is `"[DEFAULT]"`. + +Signature: + +```typescript +readonly name: string; +``` + +### Example 1 + + +```javascript +// The default app's name is "[DEFAULT]" +const app = initializeApp(defaultAppConfig); +console.log(app.name); // "[DEFAULT]" + +``` + +### Example 2 + + +```javascript +// A named app's name is what you provide to initializeApp() +const otherApp = initializeApp(otherAppConfig, "other"); +console.log(otherApp.name); // "other" + +``` + +## FirebaseApp.options + +The (read-only) configuration options for this app. These are the original parameters given in [initializeApp()](./app.md#initializeapp). + +Signature: + +```typescript +readonly options: FirebaseOptions; +``` + +### Example + + +```javascript +const app = initializeApp(config); +console.log(app.options.databaseURL === config.databaseURL); // true + +``` + diff --git a/docs-devsite/app.firebaseappsettings.md b/docs-devsite/app.firebaseappsettings.md new file mode 100644 index 00000000000..3d9f858e548 --- /dev/null +++ b/docs-devsite/app.firebaseappsettings.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FirebaseAppSettings interface +Configuration options given to [initializeApp()](./app.md#initializeapp) + +Signature: + +```typescript +export interface FirebaseAppSettings +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [automaticDataCollectionEnabled](./app.firebaseappsettings.md#firebaseappsettingsautomaticdatacollectionenabled) | boolean | The settable config flag for GDPR opt-in/opt-out | +| [name](./app.firebaseappsettings.md#firebaseappsettingsname) | string | custom name for the Firebase App. The default value is "[DEFAULT]". | + +## FirebaseAppSettings.automaticDataCollectionEnabled + +The settable config flag for GDPR opt-in/opt-out + +Signature: + +```typescript +automaticDataCollectionEnabled?: boolean; +``` + +## FirebaseAppSettings.name + +custom name for the Firebase App. The default value is `"[DEFAULT]"`. + +Signature: + +```typescript +name?: string; +``` diff --git a/docs-devsite/app.firebaseoptions.md b/docs-devsite/app.firebaseoptions.md new file mode 100644 index 00000000000..5061c901676 --- /dev/null +++ b/docs-devsite/app.firebaseoptions.md @@ -0,0 +1,112 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FirebaseOptions interface +Firebase configuration object. Contains a set of parameters required by services in order to successfully communicate with Firebase server APIs and to associate client data with your Firebase project and Firebase application. Typically this object is populated by the Firebase console at project setup. See also: [Learn about the Firebase config object](https://firebase.google.com/docs/web/setup#config-object). + +Signature: + +```typescript +export interface FirebaseOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [apiKey](./app.firebaseoptions.md#firebaseoptionsapikey) | string | An encrypted string used when calling certain APIs that don't need to access private user data (example value: AIzaSyDOCAbC123dEf456GhI789jKl012-MnO). | +| [appId](./app.firebaseoptions.md#firebaseoptionsappid) | string | Unique identifier for the app. | +| [authDomain](./app.firebaseoptions.md#firebaseoptionsauthdomain) | string | Auth domain for the project ID. | +| [databaseURL](./app.firebaseoptions.md#firebaseoptionsdatabaseurl) | string | Default Realtime Database URL. | +| [measurementId](./app.firebaseoptions.md#firebaseoptionsmeasurementid) | string | An ID automatically created when you enable Analytics in your Firebase project and register a web app. In versions 7.20.0 and higher, this parameter is optional. | +| [messagingSenderId](./app.firebaseoptions.md#firebaseoptionsmessagingsenderid) | string | Unique numerical value used to identify each sender that can send Firebase Cloud Messaging messages to client apps. | +| [projectId](./app.firebaseoptions.md#firebaseoptionsprojectid) | string | The unique identifier for the project across all of Firebase and Google Cloud. | +| [storageBucket](./app.firebaseoptions.md#firebaseoptionsstoragebucket) | string | The default Cloud Storage bucket name. | + +## FirebaseOptions.apiKey + +An encrypted string used when calling certain APIs that don't need to access private user data (example value: `AIzaSyDOCAbC123dEf456GhI789jKl012-MnO`). + +Signature: + +```typescript +apiKey?: string; +``` + +## FirebaseOptions.appId + +Unique identifier for the app. + +Signature: + +```typescript +appId?: string; +``` + +## FirebaseOptions.authDomain + +Auth domain for the project ID. + +Signature: + +```typescript +authDomain?: string; +``` + +## FirebaseOptions.databaseURL + +Default Realtime Database URL. + +Signature: + +```typescript +databaseURL?: string; +``` + +## FirebaseOptions.measurementId + +An ID automatically created when you enable Analytics in your Firebase project and register a web app. In versions 7.20.0 and higher, this parameter is optional. + +Signature: + +```typescript +measurementId?: string; +``` + +## FirebaseOptions.messagingSenderId + +Unique numerical value used to identify each sender that can send Firebase Cloud Messaging messages to client apps. + +Signature: + +```typescript +messagingSenderId?: string; +``` + +## FirebaseOptions.projectId + +The unique identifier for the project across all of Firebase and Google Cloud. + +Signature: + +```typescript +projectId?: string; +``` + +## FirebaseOptions.storageBucket + +The default Cloud Storage bucket name. + +Signature: + +```typescript +storageBucket?: string; +``` diff --git a/docs-devsite/app.md b/docs-devsite/app.md new file mode 100644 index 00000000000..babb7d7bd2b --- /dev/null +++ b/docs-devsite/app.md @@ -0,0 +1,306 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# app package +Firebase App + +This package coordinates the communication between the different Firebase components + +## Functions + +| Function | Description | +| --- | --- | +| function(app...) | +| [deleteApp(app)](./app.md#deleteapp) | Renders this app unusable and frees the resources of all associated services. | +| function() | +| [getApps()](./app.md#getapps) | A (read-only) array of all initialized apps. | +| [initializeApp()](./app.md#initializeapp) | Creates and initializes a FirebaseApp instance. | +| function(libraryKeyOrName...) | +| [registerVersion(libraryKeyOrName, version, variant)](./app.md#registerversion) | Registers a library's name and version for platform logging purposes. | +| function(logCallback...) | +| [onLog(logCallback, options)](./app.md#onlog) | Sets log handler for all Firebase SDKs. | +| function(logLevel...) | +| [setLogLevel(logLevel)](./app.md#setloglevel) | Sets log level for all Firebase SDKs.All of the log types above the current log level are captured (i.e. if you set the log level to info, errors are logged, but debug and verbose logs are not). | +| function(name...) | +| [getApp(name)](./app.md#getapp) | Retrieves a [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance.When called with no arguments, the default app is returned. When an app name is provided, the app corresponding to that name is returned.An exception is thrown if the app being retrieved has not yet been initialized. | +| function(options...) | +| [initializeApp(options, name)](./app.md#initializeapp) | Creates and initializes a [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance.See [Add Firebase to your app](https://firebase.google.com/docs/web/setup#add_firebase_to_your_app) and [Initialize multiple projects](https://firebase.google.com/docs/web/setup#multiple-projects) for detailed documentation. | +| [initializeApp(options, config)](./app.md#initializeapp) | Creates and initializes a FirebaseApp instance. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | A [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) holds the initialization information for a collection of services.Do not call this constructor directly. Instead, use [initializeApp()](./app.md#initializeapp) to create an app. | +| [FirebaseAppSettings](./app.firebaseappsettings.md#firebaseappsettings_interface) | Configuration options given to [initializeApp()](./app.md#initializeapp) | +| [FirebaseOptions](./app.firebaseoptions.md#firebaseoptions_interface) | Firebase configuration object. Contains a set of parameters required by services in order to successfully communicate with Firebase server APIs and to associate client data with your Firebase project and Firebase application. Typically this object is populated by the Firebase console at project setup. See also: [Learn about the Firebase config object](https://firebase.google.com/docs/web/setup#config-object). | + +## Variables + +| Variable | Description | +| --- | --- | +| [SDK\_VERSION](./app.md#sdk_version) | The current SDK version. | + +## deleteApp() + +Renders this app unusable and frees the resources of all associated services. + +Signature: + +```typescript +export declare function deleteApp(app: FirebaseApp): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | | + +Returns: + +Promise<void> + +### Example + + +```javascript +deleteApp(app) + .then(function() { + console.log("App deleted successfully"); + }) + .catch(function(error) { + console.log("Error deleting app:", error); + }); + +``` + +## getApps() + +A (read-only) array of all initialized apps. + +Signature: + +```typescript +export declare function getApps(): FirebaseApp[]; +``` +Returns: + +[FirebaseApp](./app.firebaseapp.md#firebaseapp_interface)\[\] + +## initializeApp() + +Creates and initializes a FirebaseApp instance. + +Signature: + +```typescript +export declare function initializeApp(): FirebaseApp; +``` +Returns: + +[FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) + +## registerVersion() + +Registers a library's name and version for platform logging purposes. + +Signature: + +```typescript +export declare function registerVersion(libraryKeyOrName: string, version: string, variant?: string): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| libraryKeyOrName | string | | +| version | string | Current version of that library. | +| variant | string | Bundle variant, e.g., node, rn, etc. | + +Returns: + +void + +## onLog() + +Sets log handler for all Firebase SDKs. + +Signature: + +```typescript +export declare function onLog(logCallback: LogCallback | null, options?: LogOptions): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| logCallback | LogCallback \| null | An optional custom log handler that executes user code whenever the Firebase SDK makes a logging call. | +| options | LogOptions | | + +Returns: + +void + +## setLogLevel() + +Sets log level for all Firebase SDKs. + +All of the log types above the current log level are captured (i.e. if you set the log level to `info`, errors are logged, but `debug` and `verbose` logs are not). + +Signature: + +```typescript +export declare function setLogLevel(logLevel: LogLevelString): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| logLevel | LogLevelString | | + +Returns: + +void + +## getApp() + +Retrieves a [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. + +When called with no arguments, the default app is returned. When an app name is provided, the app corresponding to that name is returned. + +An exception is thrown if the app being retrieved has not yet been initialized. + +Signature: + +```typescript +export declare function getApp(name?: string): FirebaseApp; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| name | string | Optional name of the app to return. If no name is provided, the default is "[DEFAULT]". | + +Returns: + +[FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) + +The app corresponding to the provided app name. If no app name is provided, the default app is returned. + +### Example 1 + + +```javascript +// Return the default app +const app = getApp(); + +``` + +### Example 2 + + +```javascript +// Return a named app +const otherApp = getApp("otherApp"); + +``` + +## initializeApp() + +Creates and initializes a [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. + +See [Add Firebase to your app](https://firebase.google.com/docs/web/setup#add_firebase_to_your_app) and [Initialize multiple projects](https://firebase.google.com/docs/web/setup#multiple-projects) for detailed documentation. + +Signature: + +```typescript +export declare function initializeApp(options: FirebaseOptions, name?: string): FirebaseApp; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| options | [FirebaseOptions](./app.firebaseoptions.md#firebaseoptions_interface) | Options to configure the app's services. | +| name | string | Optional name of the app to initialize. If no name is provided, the default is "[DEFAULT]". | + +Returns: + +[FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) + +The initialized app. + +### Example 1 + + +```javascript + +// Initialize default app +// Retrieve your own options values by adding a web app on +// https://console.firebase.google.com +initializeApp({ + apiKey: "AIza....", // Auth / General Use + authDomain: "YOUR_APP.firebaseapp.com", // Auth with popup/redirect + databaseURL: "https://YOUR_APP.firebaseio.com", // Realtime Database + storageBucket: "YOUR_APP.appspot.com", // Storage + messagingSenderId: "123456789" // Cloud Messaging +}); + +``` + +### Example 2 + + +```javascript + +// Initialize another app +const otherApp = initializeApp({ + databaseURL: "https://.firebaseio.com", + storageBucket: ".appspot.com" +}, "otherApp"); + +``` + +## initializeApp() + +Creates and initializes a FirebaseApp instance. + +Signature: + +```typescript +export declare function initializeApp(options: FirebaseOptions, config?: FirebaseAppSettings): FirebaseApp; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| options | [FirebaseOptions](./app.firebaseoptions.md#firebaseoptions_interface) | Options to configure the app's services. | +| config | [FirebaseAppSettings](./app.firebaseappsettings.md#firebaseappsettings_interface) | FirebaseApp Configuration | + +Returns: + +[FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) + +## SDK\_VERSION + +The current SDK version. + +Signature: + +```typescript +SDK_VERSION: string +``` diff --git a/docs-devsite/auth.actioncodeinfo.md b/docs-devsite/auth.actioncodeinfo.md new file mode 100644 index 00000000000..980acf6d967 --- /dev/null +++ b/docs-devsite/auth.actioncodeinfo.md @@ -0,0 +1,58 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ActionCodeInfo interface +A response from [checkActionCode()](./auth.md#checkactioncode). + +Signature: + +```typescript +export interface ActionCodeInfo +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [data](./auth.actioncodeinfo.md#actioncodeinfodata) | { email?: string \| null; multiFactorInfo?: [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) \| null; previousEmail?: string \| null; } | The data associated with the action code. | +| [operation](./auth.actioncodeinfo.md#actioncodeinfooperation) | typeof [ActionCodeOperationMap](./auth.md#actioncodeoperation)\[keyof typeof [ActionCodeOperationMap](./auth.md#actioncodeoperation)\] | The type of operation that generated the action code. | + +## ActionCodeInfo.data + +The data associated with the action code. + +For the [ActionCodeOperation](./auth.md#actioncodeoperation).PASSWORD\_RESET, [ActionCodeOperation](./auth.md#actioncodeoperation).VERIFY\_EMAIL, and [ActionCodeOperation](./auth.md#actioncodeoperation).RECOVER\_EMAIL actions, this object contains an email field with the address the email was sent to. + +For the [ActionCodeOperation](./auth.md#actioncodeoperation).RECOVER\_EMAIL action, which allows a user to undo an email address change, this object also contains a `previousEmail` field with the user account's current email address. After the action completes, the user's email address will revert to the value in the `email` field from the value in `previousEmail` field. + +For the [ActionCodeOperation](./auth.md#actioncodeoperation).VERIFY\_AND\_CHANGE\_EMAIL action, which allows a user to verify the email before updating it, this object contains a `previousEmail` field with the user account's email address before updating. After the action completes, the user's email address will be updated to the value in the `email` field from the value in `previousEmail` field. + +For the [ActionCodeOperation](./auth.md#actioncodeoperation).REVERT\_SECOND\_FACTOR\_ADDITION action, which allows a user to unenroll a newly added second factor, this object contains a `multiFactorInfo` field with the information about the second factor. For phone second factor, the `multiFactorInfo` is a [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) object, which contains the phone number. + +Signature: + +```typescript +data: { + email?: string | null; + multiFactorInfo?: MultiFactorInfo | null; + previousEmail?: string | null; + }; +``` + +## ActionCodeInfo.operation + +The type of operation that generated the action code. + +Signature: + +```typescript +operation: typeof ActionCodeOperationMap[keyof typeof ActionCodeOperationMap]; +``` diff --git a/docs-devsite/auth.actioncodesettings.md b/docs-devsite/auth.actioncodesettings.md new file mode 100644 index 00000000000..a12144adaf4 --- /dev/null +++ b/docs-devsite/auth.actioncodesettings.md @@ -0,0 +1,95 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ActionCodeSettings interface +An interface that defines the required continue/state URL with optional Android and iOS bundle identifiers. + +Signature: + +```typescript +export interface ActionCodeSettings +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [android](./auth.actioncodesettings.md#actioncodesettingsandroid) | { installApp?: boolean; minimumVersion?: string; packageName: string; } | Sets the Android package name. | +| [dynamicLinkDomain](./auth.actioncodesettings.md#actioncodesettingsdynamiclinkdomain) | string | When multiple custom dynamic link domains are defined for a project, specify which one to use when the link is to be opened via a specified mobile app (for example, example.page.link). | +| [handleCodeInApp](./auth.actioncodesettings.md#actioncodesettingshandlecodeinapp) | boolean | When set to true, the action code link will be be sent as a Universal Link or Android App Link and will be opened by the app if installed. | +| [iOS](./auth.actioncodesettings.md#actioncodesettingsios) | { bundleId: string; } | Sets the iOS bundle ID. | +| [url](./auth.actioncodesettings.md#actioncodesettingsurl) | string | Sets the link continue/state URL. | + +## ActionCodeSettings.android + +Sets the Android package name. + +This will try to open the link in an android app if it is installed. If `installApp` is passed, it specifies whether to install the Android app if the device supports it and the app is not already installed. If this field is provided without a `packageName`, an error is thrown explaining that the `packageName` must be provided in conjunction with this field. If `minimumVersion` is specified, and an older version of the app is installed, the user is taken to the Play Store to upgrade the app. + +Signature: + +```typescript +android?: { + installApp?: boolean; + minimumVersion?: string; + packageName: string; + }; +``` + +## ActionCodeSettings.dynamicLinkDomain + +When multiple custom dynamic link domains are defined for a project, specify which one to use when the link is to be opened via a specified mobile app (for example, `example.page.link`). + +Signature: + +```typescript +dynamicLinkDomain?: string; +``` + +## ActionCodeSettings.handleCodeInApp + +When set to true, the action code link will be be sent as a Universal Link or Android App Link and will be opened by the app if installed. + +In the false case, the code will be sent to the web widget first and then on continue will redirect to the app if installed. + +Signature: + +```typescript +handleCodeInApp?: boolean; +``` + +## ActionCodeSettings.iOS + +Sets the iOS bundle ID. + +This will try to open the link in an iOS app if it is installed. + +App installation is not supported for iOS. + +Signature: + +```typescript +iOS?: { + bundleId: string; + }; +``` + +## ActionCodeSettings.url + +Sets the link continue/state URL. + +This has different meanings in different contexts: - When the link is handled in the web action widgets, this is the deep link in the `continueUrl` query parameter. - When the link is handled in the app directly, this is the `continueUrl` query parameter in the deep link of the Dynamic Link. + +Signature: + +```typescript +url: string; +``` diff --git a/docs-devsite/auth.actioncodeurl.md b/docs-devsite/auth.actioncodeurl.md new file mode 100644 index 00000000000..f59e20d8c15 --- /dev/null +++ b/docs-devsite/auth.actioncodeurl.md @@ -0,0 +1,121 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ActionCodeURL class +A utility class to parse email action URLs such as password reset, email verification, email link sign in, etc. + +The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `ActionCodeURL` class. + +Signature: + +```typescript +export declare class ActionCodeURL +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [apiKey](./auth.actioncodeurl.md#actioncodeurlapikey) | | string | The API key of the email action link. | +| [code](./auth.actioncodeurl.md#actioncodeurlcode) | | string | The action code of the email action link. | +| [continueUrl](./auth.actioncodeurl.md#actioncodeurlcontinueurl) | | string \| null | The continue URL of the email action link. Null if not provided. | +| [languageCode](./auth.actioncodeurl.md#actioncodeurllanguagecode) | | string \| null | The language code of the email action link. Null if not provided. | +| [operation](./auth.actioncodeurl.md#actioncodeurloperation) | | string | The action performed by the email action link. It returns from one of the types from [ActionCodeInfo](./auth.actioncodeinfo.md#actioncodeinfo_interface) | +| [tenantId](./auth.actioncodeurl.md#actioncodeurltenantid) | | string \| null | The tenant ID of the email action link. Null if the email action is from the parent project. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [parseLink(link)](./auth.actioncodeurl.md#actioncodeurlparselink) | static | Parses the email action link string and returns an [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) if the link is valid, otherwise returns null. | + +## ActionCodeURL.apiKey + +The API key of the email action link. + +Signature: + +```typescript +readonly apiKey: string; +``` + +## ActionCodeURL.code + +The action code of the email action link. + +Signature: + +```typescript +readonly code: string; +``` + +## ActionCodeURL.continueUrl + +The continue URL of the email action link. Null if not provided. + +Signature: + +```typescript +readonly continueUrl: string | null; +``` + +## ActionCodeURL.languageCode + +The language code of the email action link. Null if not provided. + +Signature: + +```typescript +readonly languageCode: string | null; +``` + +## ActionCodeURL.operation + +The action performed by the email action link. It returns from one of the types from [ActionCodeInfo](./auth.actioncodeinfo.md#actioncodeinfo_interface) + +Signature: + +```typescript +readonly operation: string; +``` + +## ActionCodeURL.tenantId + +The tenant ID of the email action link. Null if the email action is from the parent project. + +Signature: + +```typescript +readonly tenantId: string | null; +``` + +## ActionCodeURL.parseLink() + +Parses the email action link string and returns an [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) if the link is valid, otherwise returns null. + +Signature: + +```typescript +static parseLink(link: string): ActionCodeURL | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| link | string | The email action link string. | + +Returns: + +[ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) \| null + +The [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) object, or null if the link is invalid. + diff --git a/docs-devsite/auth.additionaluserinfo.md b/docs-devsite/auth.additionaluserinfo.md new file mode 100644 index 00000000000..ec6ca5740ac --- /dev/null +++ b/docs-devsite/auth.additionaluserinfo.md @@ -0,0 +1,68 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AdditionalUserInfo interface +A structure containing additional user information from a federated identity provider. + +Signature: + +```typescript +export interface AdditionalUserInfo +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [isNewUser](./auth.additionaluserinfo.md#additionaluserinfoisnewuser) | boolean | Whether the user is new (created via sign-up) or existing (authenticated using sign-in). | +| [profile](./auth.additionaluserinfo.md#additionaluserinfoprofile) | Record<string, unknown> \| null | Map containing IDP-specific user data. | +| [providerId](./auth.additionaluserinfo.md#additionaluserinfoproviderid) | string \| null | Identifier for the provider used to authenticate this user. | +| [username](./auth.additionaluserinfo.md#additionaluserinfousername) | string \| null | The username if the provider is GitHub or Twitter. | + +## AdditionalUserInfo.isNewUser + +Whether the user is new (created via sign-up) or existing (authenticated using sign-in). + +Signature: + +```typescript +readonly isNewUser: boolean; +``` + +## AdditionalUserInfo.profile + +Map containing IDP-specific user data. + +Signature: + +```typescript +readonly profile: Record | null; +``` + +## AdditionalUserInfo.providerId + +Identifier for the provider used to authenticate this user. + +Signature: + +```typescript +readonly providerId: string | null; +``` + +## AdditionalUserInfo.username + +The username if the provider is GitHub or Twitter. + +Signature: + +```typescript +readonly username?: string | null; +``` diff --git a/docs-devsite/auth.applicationverifier.md b/docs-devsite/auth.applicationverifier.md new file mode 100644 index 00000000000..08e81aa3362 --- /dev/null +++ b/docs-devsite/auth.applicationverifier.md @@ -0,0 +1,59 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ApplicationVerifier interface +A verifier for domain verification and abuse prevention. + +Currently, the only implementation is [RecaptchaVerifier](./auth.recaptchaverifier.md#recaptchaverifier_class). + +Signature: + +```typescript +export interface ApplicationVerifier +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [type](./auth.applicationverifier.md#applicationverifiertype) | string | Identifies the type of application verifier (e.g. "recaptcha"). | + +## Methods + +| Method | Description | +| --- | --- | +| [verify()](./auth.applicationverifier.md#applicationverifierverify) | Executes the verification process. | + +## ApplicationVerifier.type + +Identifies the type of application verifier (e.g. "recaptcha"). + +Signature: + +```typescript +readonly type: string; +``` + +## ApplicationVerifier.verify() + +Executes the verification process. + +Signature: + +```typescript +verify(): Promise; +``` +Returns: + +Promise<string> + +A Promise for a token that can be used to assert the validity of a request. + diff --git a/docs-devsite/auth.auth.md b/docs-devsite/auth.auth.md new file mode 100644 index 00000000000..9bd59ba6c56 --- /dev/null +++ b/docs-devsite/auth.auth.md @@ -0,0 +1,299 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Auth interface +Interface representing Firebase Auth service. + +See [Firebase Authentication](https://firebase.google.com/docs/auth/) for a full guide on how to use the Firebase Auth service. + +Signature: + +```typescript +export interface Auth +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [app](./auth.auth.md#authapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with the Auth service instance. | +| [config](./auth.auth.md#authconfig) | [Config](./auth.config.md#config_interface) | The [Config](./auth.config.md#config_interface) used to initialize this instance. | +| [currentUser](./auth.auth.md#authcurrentuser) | [User](./auth.user.md#user_interface) \| null | The currently signed-in user (or null). | +| [emulatorConfig](./auth.auth.md#authemulatorconfig) | [EmulatorConfig](./auth.emulatorconfig.md#emulatorconfig_interface) \| null | The current emulator configuration (or null). | +| [languageCode](./auth.auth.md#authlanguagecode) | string \| null | The [Auth](./auth.auth.md#auth_interface) instance's language code. | +| [name](./auth.auth.md#authname) | string | The name of the app associated with the Auth service instance. | +| [settings](./auth.auth.md#authsettings) | [AuthSettings](./auth.authsettings.md#authsettings_interface) | The [Auth](./auth.auth.md#auth_interface) instance's settings. | +| [tenantId](./auth.auth.md#authtenantid) | string \| null | The [Auth](./auth.auth.md#auth_interface) instance's tenant ID. | + +## Methods + +| Method | Description | +| --- | --- | +| [beforeAuthStateChanged(callback, onAbort)](./auth.auth.md#authbeforeauthstatechanged) | Adds a blocking callback that runs before an auth state change sets a new user. | +| [onAuthStateChanged(nextOrObserver, error, completed)](./auth.auth.md#authonauthstatechanged) | Adds an observer for changes to the user's sign-in state. | +| [onIdTokenChanged(nextOrObserver, error, completed)](./auth.auth.md#authonidtokenchanged) | Adds an observer for changes to the signed-in user's ID token. | +| [setPersistence(persistence)](./auth.auth.md#authsetpersistence) | Changes the type of persistence on the Auth instance. | +| [signOut()](./auth.auth.md#authsignout) | Signs out the current user. | +| [updateCurrentUser(user)](./auth.auth.md#authupdatecurrentuser) | Asynchronously sets the provided user as [Auth.currentUser](./auth.auth.md#authcurrentuser) on the [Auth](./auth.auth.md#auth_interface) instance. | +| [useDeviceLanguage()](./auth.auth.md#authusedevicelanguage) | Sets the current language to the default device/browser preference. | + +## Auth.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with the `Auth` service instance. + +Signature: + +```typescript +readonly app: FirebaseApp; +``` + +## Auth.config + +The [Config](./auth.config.md#config_interface) used to initialize this instance. + +Signature: + +```typescript +readonly config: Config; +``` + +## Auth.currentUser + +The currently signed-in user (or null). + +Signature: + +```typescript +readonly currentUser: User | null; +``` + +## Auth.emulatorConfig + +The current emulator configuration (or null). + +Signature: + +```typescript +readonly emulatorConfig: EmulatorConfig | null; +``` + +## Auth.languageCode + +The [Auth](./auth.auth.md#auth_interface) instance's language code. + +This is a readable/writable property. When set to null, the default Firebase Console language setting is applied. The language code will propagate to email action templates (password reset, email verification and email change revocation), SMS templates for phone authentication, reCAPTCHA verifier and OAuth popup/redirect operations provided the specified providers support localization with the language code specified. + +Signature: + +```typescript +languageCode: string | null; +``` + +## Auth.name + +The name of the app associated with the `Auth` service instance. + +Signature: + +```typescript +readonly name: string; +``` + +## Auth.settings + +The [Auth](./auth.auth.md#auth_interface) instance's settings. + +This is used to edit/read configuration related options such as app verification mode for phone authentication. + +Signature: + +```typescript +readonly settings: AuthSettings; +``` + +## Auth.tenantId + +The [Auth](./auth.auth.md#auth_interface) instance's tenant ID. + +This is a readable/writable property. When you set the tenant ID of an [Auth](./auth.auth.md#auth_interface) instance, all future sign-in/sign-up operations will pass this tenant ID and sign in or sign up users to the specified tenant project. When set to null, users are signed in to the parent project. + +Signature: + +```typescript +tenantId: string | null; +``` + +### Example + + +```javascript +// Set the tenant ID on Auth instance. +auth.tenantId = 'TENANT_PROJECT_ID'; + +// All future sign-in request now include tenant ID. +const result = await signInWithEmailAndPassword(auth, email, password); +// result.user.tenantId should be 'TENANT_PROJECT_ID'. + +``` + +## Auth.beforeAuthStateChanged() + +Adds a blocking callback that runs before an auth state change sets a new user. + +Signature: + +```typescript +beforeAuthStateChanged(callback: (user: User | null) => void | Promise, onAbort?: () => void): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| callback | (user: [User](./auth.user.md#user_interface) \| null) => void \| Promise<void> | callback triggered before new user value is set. If this throws, it blocks the user from being set. | +| onAbort | () => void | callback triggered if a later beforeAuthStateChanged() callback throws, allowing you to undo any side effects. | + +Returns: + +[Unsubscribe](./util.md#unsubscribe) + +## Auth.onAuthStateChanged() + +Adds an observer for changes to the user's sign-in state. + +To keep the old behavior, see [Auth.onIdTokenChanged()](./auth.auth.md#authonidtokenchanged). + +Signature: + +```typescript +onAuthStateChanged(nextOrObserver: NextOrObserver, error?: ErrorFn, completed?: CompleteFn): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| nextOrObserver | [NextOrObserver](./auth.md#nextorobserver)<[User](./auth.user.md#user_interface) \| null> | callback triggered on change. | +| error | [ErrorFn](./util.md#errorfn) | Deprecated. This callback is never triggered. Errors on signing in/out can be caught in promises returned from sign-in/sign-out functions. | +| completed | [CompleteFn](./util.md#completefn) | Deprecated. This callback is never triggered. | + +Returns: + +[Unsubscribe](./util.md#unsubscribe) + +## Auth.onIdTokenChanged() + +Adds an observer for changes to the signed-in user's ID token. + +This includes sign-in, sign-out, and token refresh events. + +Signature: + +```typescript +onIdTokenChanged(nextOrObserver: NextOrObserver, error?: ErrorFn, completed?: CompleteFn): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| nextOrObserver | [NextOrObserver](./auth.md#nextorobserver)<[User](./auth.user.md#user_interface) \| null> | callback triggered on change. | +| error | [ErrorFn](./util.md#errorfn) | Deprecated. This callback is never triggered. Errors on signing in/out can be caught in promises returned from sign-in/sign-out functions. | +| completed | [CompleteFn](./util.md#completefn) | Deprecated. This callback is never triggered. | + +Returns: + +[Unsubscribe](./util.md#unsubscribe) + +## Auth.setPersistence() + +Changes the type of persistence on the `Auth` instance. + +This will affect the currently saved Auth session and applies this type of persistence for future sign-in requests, including sign-in with redirect requests. + +This makes it easy for a user signing in to specify whether their session should be remembered or not. It also makes it easier to never persist the Auth state for applications that are shared by other users or have sensitive data. + +Signature: + +```typescript +setPersistence(persistence: Persistence): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| persistence | [Persistence](./auth.persistence.md#persistence_interface) | The [Persistence](./auth.persistence.md#persistence_interface) to use. | + +Returns: + +Promise<void> + +### Example + + +```javascript +auth.setPersistence(browserSessionPersistence); + +``` + +## Auth.signOut() + +Signs out the current user. + +Signature: + +```typescript +signOut(): Promise; +``` +Returns: + +Promise<void> + +## Auth.updateCurrentUser() + +Asynchronously sets the provided user as [Auth.currentUser](./auth.auth.md#authcurrentuser) on the [Auth](./auth.auth.md#auth_interface) instance. + +A new instance copy of the user provided will be made and set as currentUser. + +This will trigger [Auth.onAuthStateChanged()](./auth.auth.md#authonauthstatechanged) and [Auth.onIdTokenChanged()](./auth.auth.md#authonidtokenchanged) listeners like other sign in methods. + +The operation fails with an error if the user to be updated belongs to a different Firebase project. + +Signature: + +```typescript +updateCurrentUser(user: User | null): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) \| null | The new [User](./auth.user.md#user_interface). | + +Returns: + +Promise<void> + +## Auth.useDeviceLanguage() + +Sets the current language to the default device/browser preference. + +Signature: + +```typescript +useDeviceLanguage(): void; +``` +Returns: + +void + diff --git a/docs-devsite/auth.authcredential.md b/docs-devsite/auth.authcredential.md new file mode 100644 index 00000000000..fdc6fe392c4 --- /dev/null +++ b/docs-devsite/auth.authcredential.md @@ -0,0 +1,76 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AuthCredential class +Interface that represents the credentials returned by an [AuthProvider](./auth.authprovider.md#authprovider_interface). + +Implementations specify the details about each auth provider's credential requirements. + +The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `AuthCredential` class. + +Signature: + +```typescript +export declare class AuthCredential +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [providerId](./auth.authcredential.md#authcredentialproviderid) | | string | The authentication provider ID for the credential. | +| [signInMethod](./auth.authcredential.md#authcredentialsigninmethod) | | string | The authentication sign in method for the credential. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [toJSON()](./auth.authcredential.md#authcredentialtojson) | | Returns a JSON-serializable representation of this object. | + +## AuthCredential.providerId + +The authentication provider ID for the credential. + +For example, 'facebook.com', or 'google.com'. + +Signature: + +```typescript +readonly providerId: string; +``` + +## AuthCredential.signInMethod + +The authentication sign in method for the credential. + +For example, [SignInMethod](./auth.md#signinmethod).EMAIL\_PASSWORD, or [SignInMethod](./auth.md#signinmethod).EMAIL\_LINK. This corresponds to the sign-in method identifier as returned in [fetchSignInMethodsForEmail()](./auth.md#fetchsigninmethodsforemail). + +Signature: + +```typescript +readonly signInMethod: string; +``` + +## AuthCredential.toJSON() + +Returns a JSON-serializable representation of this object. + +Signature: + +```typescript +toJSON(): object; +``` +Returns: + +object + +a JSON-serializable representation of this object. + diff --git a/docs-devsite/auth.autherror.md b/docs-devsite/auth.autherror.md new file mode 100644 index 00000000000..f91b835b5ed --- /dev/null +++ b/docs-devsite/auth.autherror.md @@ -0,0 +1,41 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AuthError interface +Interface for an `Auth` error. + +Signature: + +```typescript +export interface AuthError extends FirebaseError +``` +Extends: [FirebaseError](./util.firebaseerror.md#firebaseerror_class) + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [customData](./auth.autherror.md#autherrorcustomdata) | { readonly appName: string; readonly email?: string; readonly phoneNumber?: string; readonly tenantId?: string; } | Details about the Firebase Auth error. | + +## AuthError.customData + +Details about the Firebase Auth error. + +Signature: + +```typescript +readonly customData: { + readonly appName: string; + readonly email?: string; + readonly phoneNumber?: string; + readonly tenantId?: string; + }; +``` diff --git a/docs-devsite/auth.autherrormap.md b/docs-devsite/auth.autherrormap.md new file mode 100644 index 00000000000..e0316a8ed59 --- /dev/null +++ b/docs-devsite/auth.autherrormap.md @@ -0,0 +1,27 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AuthErrorMap interface +A mapping of error codes to error messages. + +While error messages are useful for debugging (providing verbose textual context around what went wrong), these strings take up a lot of space in the compiled code. When deploying code in production, using [prodErrorMap](./auth.md#proderrormap) will save you roughly 10k compressed/gzipped over [debugErrorMap](./auth.md#debugerrormap). You can select the error map during initialization: + +```javascript +initializeAuth(app, {errorMap: debugErrorMap}) + +``` +When initializing Auth, [prodErrorMap](./auth.md#proderrormap) is default. + +Signature: + +```typescript +export interface AuthErrorMap +``` diff --git a/docs-devsite/auth.authprovider.md b/docs-devsite/auth.authprovider.md new file mode 100644 index 00000000000..a9871dad0a8 --- /dev/null +++ b/docs-devsite/auth.authprovider.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AuthProvider interface +Interface that represents an auth provider, used to facilitate creating [AuthCredential](./auth.authcredential.md#authcredential_class). + +Signature: + +```typescript +export interface AuthProvider +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [providerId](./auth.authprovider.md#authproviderproviderid) | string | Provider for which credentials can be constructed. | + +## AuthProvider.providerId + +Provider for which credentials can be constructed. + +Signature: + +```typescript +readonly providerId: string; +``` diff --git a/docs-devsite/auth.authsettings.md b/docs-devsite/auth.authsettings.md new file mode 100644 index 00000000000..c54fac47da4 --- /dev/null +++ b/docs-devsite/auth.authsettings.md @@ -0,0 +1,41 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AuthSettings interface +Interface representing an [Auth](./auth.auth.md#auth_interface) instance's settings. + +Currently used for enabling/disabling app verification for phone Auth testing. + +Signature: + +```typescript +export interface AuthSettings +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [appVerificationDisabledForTesting](./auth.authsettings.md#authsettingsappverificationdisabledfortesting) | boolean | When set, this property disables app verification for the purpose of testing phone authentication. For this property to take effect, it needs to be set before rendering a reCAPTCHA app verifier. When this is disabled, a mock reCAPTCHA is rendered instead. This is useful for manual testing during development or for automated integration tests.In order to use this feature, you will need to [whitelist your phone number](https://firebase.google.com/docs/auth/web/phone-auth#test-with-whitelisted-phone-numbers) via the Firebase Console.The default value is false (app verification is enabled). | + +## AuthSettings.appVerificationDisabledForTesting + +When set, this property disables app verification for the purpose of testing phone authentication. For this property to take effect, it needs to be set before rendering a reCAPTCHA app verifier. When this is disabled, a mock reCAPTCHA is rendered instead. This is useful for manual testing during development or for automated integration tests. + +In order to use this feature, you will need to [whitelist your phone number](https://firebase.google.com/docs/auth/web/phone-auth#test-with-whitelisted-phone-numbers) via the Firebase Console. + +The default value is false (app verification is enabled). + +Signature: + +```typescript +appVerificationDisabledForTesting: boolean; +``` diff --git a/docs-devsite/auth.config.md b/docs-devsite/auth.config.md new file mode 100644 index 00000000000..c22a3930f87 --- /dev/null +++ b/docs-devsite/auth.config.md @@ -0,0 +1,90 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Config interface +Interface representing the `Auth` config. + +Signature: + +```typescript +export interface Config +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [apiHost](./auth.config.md#configapihost) | string | The host at which the Firebase Auth backend is running. | +| [apiKey](./auth.config.md#configapikey) | string | The API Key used to communicate with the Firebase Auth backend. | +| [apiScheme](./auth.config.md#configapischeme) | string | The scheme used to communicate with the Firebase Auth backend. | +| [authDomain](./auth.config.md#configauthdomain) | string | The domain at which the web widgets are hosted (provided via Firebase Config). | +| [sdkClientVersion](./auth.config.md#configsdkclientversion) | string | The SDK Client Version. | +| [tokenApiHost](./auth.config.md#configtokenapihost) | string | The host at which the Secure Token API is running. | + +## Config.apiHost + +The host at which the Firebase Auth backend is running. + +Signature: + +```typescript +apiHost: string; +``` + +## Config.apiKey + +The API Key used to communicate with the Firebase Auth backend. + +Signature: + +```typescript +apiKey: string; +``` + +## Config.apiScheme + +The scheme used to communicate with the Firebase Auth backend. + +Signature: + +```typescript +apiScheme: string; +``` + +## Config.authDomain + +The domain at which the web widgets are hosted (provided via Firebase Config). + +Signature: + +```typescript +authDomain?: string; +``` + +## Config.sdkClientVersion + +The SDK Client Version. + +Signature: + +```typescript +sdkClientVersion: string; +``` + +## Config.tokenApiHost + +The host at which the Secure Token API is running. + +Signature: + +```typescript +tokenApiHost: string; +``` diff --git a/docs-devsite/auth.confirmationresult.md b/docs-devsite/auth.confirmationresult.md new file mode 100644 index 00000000000..5d6a209b12d --- /dev/null +++ b/docs-devsite/auth.confirmationresult.md @@ -0,0 +1,74 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ConfirmationResult interface +A result from a phone number sign-in, link, or reauthenticate call. + +Signature: + +```typescript +export interface ConfirmationResult +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [verificationId](./auth.confirmationresult.md#confirmationresultverificationid) | string | The phone number authentication operation's verification ID. | + +## Methods + +| Method | Description | +| --- | --- | +| [confirm(verificationCode)](./auth.confirmationresult.md#confirmationresultconfirm) | Finishes a phone number sign-in, link, or reauthentication. | + +## ConfirmationResult.verificationId + +The phone number authentication operation's verification ID. + +This can be used along with the verification code to initialize a [PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class). + +Signature: + +```typescript +readonly verificationId: string; +``` + +## ConfirmationResult.confirm() + +Finishes a phone number sign-in, link, or reauthentication. + +Signature: + +```typescript +confirm(verificationCode: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| verificationCode | string | The code that was sent to the user's mobile device. | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> + +### Example + + +```javascript +const confirmationResult = await signInWithPhoneNumber(auth, phoneNumber, applicationVerifier); +// Obtain verificationCode from the user. +const userCredential = await confirmationResult.confirm(verificationCode); + +``` + diff --git a/docs-devsite/auth.dependencies.md b/docs-devsite/auth.dependencies.md new file mode 100644 index 00000000000..9112f016fa1 --- /dev/null +++ b/docs-devsite/auth.dependencies.md @@ -0,0 +1,63 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Dependencies interface +The dependencies that can be used to initialize an [Auth](./auth.auth.md#auth_interface) instance. + +The modular SDK enables tree shaking by allowing explicit declarations of dependencies. For example, a web app does not need to include code that enables Cordova redirect sign in. That functionality is therefore split into [browserPopupRedirectResolver](./auth.md#browserpopupredirectresolver) and [cordovaPopupRedirectResolver](./auth.md#cordovapopupredirectresolver). The dependencies object is how Auth is configured to reduce bundle sizes. + +There are two ways to initialize an [Auth](./auth.auth.md#auth_interface) instance: [getAuth()](./auth.md#getauth) and [initializeAuth()](./auth.md#initializeauth). `getAuth` initializes everything using platform-specific configurations, while `initializeAuth` takes a `Dependencies` object directly, giving you more control over what is used. + +Signature: + +```typescript +export interface Dependencies +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [errorMap](./auth.dependencies.md#dependencieserrormap) | [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) | Which [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) to use. | +| [persistence](./auth.dependencies.md#dependenciespersistence) | [Persistence](./auth.persistence.md#persistence_interface) \| [Persistence](./auth.persistence.md#persistence_interface)\[\] | Which [Persistence](./auth.persistence.md#persistence_interface) to use. If this is an array, the first Persistence that the device supports is used. The SDK searches for an existing account in order and, if one is found in a secondary Persistence, the account is moved to the primary Persistence.If no persistence is provided, the SDK falls back on [inMemoryPersistence](./auth.md#inmemorypersistence). | +| [popupRedirectResolver](./auth.dependencies.md#dependenciespopupredirectresolver) | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | The [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) to use. This value depends on the platform. Options are [browserPopupRedirectResolver](./auth.md#browserpopupredirectresolver) and [cordovaPopupRedirectResolver](./auth.md#cordovapopupredirectresolver). This field is optional if neither [signInWithPopup()](./auth.md#signinwithpopup) or [signInWithRedirect()](./auth.md#signinwithredirect) are being used. | + +## Dependencies.errorMap + +Which [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) to use. + +Signature: + +```typescript +errorMap?: AuthErrorMap; +``` + +## Dependencies.persistence + +Which [Persistence](./auth.persistence.md#persistence_interface) to use. If this is an array, the first `Persistence` that the device supports is used. The SDK searches for an existing account in order and, if one is found in a secondary `Persistence`, the account is moved to the primary `Persistence`. + +If no persistence is provided, the SDK falls back on [inMemoryPersistence](./auth.md#inmemorypersistence). + +Signature: + +```typescript +persistence?: Persistence | Persistence[]; +``` + +## Dependencies.popupRedirectResolver + +The [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) to use. This value depends on the platform. Options are [browserPopupRedirectResolver](./auth.md#browserpopupredirectresolver) and [cordovaPopupRedirectResolver](./auth.md#cordovapopupredirectresolver). This field is optional if neither [signInWithPopup()](./auth.md#signinwithpopup) or [signInWithRedirect()](./auth.md#signinwithredirect) are being used. + +Signature: + +```typescript +popupRedirectResolver?: PopupRedirectResolver; +``` diff --git a/docs-devsite/auth.emailauthcredential.md b/docs-devsite/auth.emailauthcredential.md new file mode 100644 index 00000000000..5d322574b02 --- /dev/null +++ b/docs-devsite/auth.emailauthcredential.md @@ -0,0 +1,69 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# EmailAuthCredential class +Interface that represents the credentials returned by [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) for [ProviderId](./auth.md#providerid).PASSWORD + +Covers both [SignInMethod](./auth.md#signinmethod).EMAIL\_PASSWORD and [SignInMethod](./auth.md#signinmethod).EMAIL\_LINK. + +The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `EmailAuthCredential` class. + +Signature: + +```typescript +export declare class EmailAuthCredential extends AuthCredential +``` +Extends: [AuthCredential](./auth.authcredential.md#authcredential_class) + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [fromJSON(json)](./auth.emailauthcredential.md#emailauthcredentialfromjson) | static | Static method to deserialize a JSON representation of an object into an [AuthCredential](./auth.authcredential.md#authcredential_class). | +| [toJSON()](./auth.emailauthcredential.md#emailauthcredentialtojson) | | Returns a JSON-serializable representation of this object. | + +## EmailAuthCredential.fromJSON() + +Static method to deserialize a JSON representation of an object into an [AuthCredential](./auth.authcredential.md#authcredential_class). + +Signature: + +```typescript +static fromJSON(json: object | string): EmailAuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| json | object \| string | Either object or the stringified representation of the object. When string is provided, JSON.parse would be called first. | + +Returns: + +[EmailAuthCredential](./auth.emailauthcredential.md#emailauthcredential_class) \| null + +If the JSON input does not represent an [AuthCredential](./auth.authcredential.md#authcredential_class), null is returned. + +## EmailAuthCredential.toJSON() + +Returns a JSON-serializable representation of this object. + +Signature: + +```typescript +toJSON(): object; +``` +Returns: + +object + +a JSON-serializable representation of this object. + diff --git a/docs-devsite/auth.emailauthprovider.md b/docs-devsite/auth.emailauthprovider.md new file mode 100644 index 00000000000..c1834b1b8c4 --- /dev/null +++ b/docs-devsite/auth.emailauthprovider.md @@ -0,0 +1,159 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# EmailAuthProvider class +Provider for generating [EmailAuthCredential](./auth.emailauthcredential.md#emailauthcredential_class). + +Signature: + +```typescript +export declare class EmailAuthProvider implements AuthProvider +``` +Implements: [AuthProvider](./auth.authprovider.md#authprovider_interface) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [EMAIL\_LINK\_SIGN\_IN\_METHOD](./auth.emailauthprovider.md#emailauthprovideremail_link_sign_in_method) | static | 'emailLink' | Always set to [SignInMethod](./auth.md#signinmethod).EMAIL\_LINK. | +| [EMAIL\_PASSWORD\_SIGN\_IN\_METHOD](./auth.emailauthprovider.md#emailauthprovideremail_password_sign_in_method) | static | 'password' | Always set to [SignInMethod](./auth.md#signinmethod).EMAIL\_PASSWORD. | +| [PROVIDER\_ID](./auth.emailauthprovider.md#emailauthproviderprovider_id) | static | 'password' | Always set to [ProviderId](./auth.md#providerid).PASSWORD, even for email link. | +| [providerId](./auth.emailauthprovider.md#emailauthproviderproviderid) | | "password" | Always set to [ProviderId](./auth.md#providerid).PASSWORD, even for email link. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [credential(email, password)](./auth.emailauthprovider.md#emailauthprovidercredential) | static | Initialize an [AuthCredential](./auth.authcredential.md#authcredential_class) using an email and password. | +| [credentialWithLink(email, emailLink)](./auth.emailauthprovider.md#emailauthprovidercredentialwithlink) | static | Initialize an [AuthCredential](./auth.authcredential.md#authcredential_class) using an email and an email link after a sign in with email link operation. | + +## EmailAuthProvider.EMAIL\_LINK\_SIGN\_IN\_METHOD + +Always set to [SignInMethod](./auth.md#signinmethod).EMAIL\_LINK. + +Signature: + +```typescript +static readonly EMAIL_LINK_SIGN_IN_METHOD: 'emailLink'; +``` + +## EmailAuthProvider.EMAIL\_PASSWORD\_SIGN\_IN\_METHOD + +Always set to [SignInMethod](./auth.md#signinmethod).EMAIL\_PASSWORD. + +Signature: + +```typescript +static readonly EMAIL_PASSWORD_SIGN_IN_METHOD: 'password'; +``` + +## EmailAuthProvider.PROVIDER\_ID + +Always set to [ProviderId](./auth.md#providerid).PASSWORD, even for email link. + +Signature: + +```typescript +static readonly PROVIDER_ID: 'password'; +``` + +## EmailAuthProvider.providerId + +Always set to [ProviderId](./auth.md#providerid).PASSWORD, even for email link. + +Signature: + +```typescript +readonly providerId: "password"; +``` + +## EmailAuthProvider.credential() + +Initialize an [AuthCredential](./auth.authcredential.md#authcredential_class) using an email and password. + +Signature: + +```typescript +static credential(email: string, password: string): EmailAuthCredential; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| email | string | Email address. | +| password | string | User account password. | + +Returns: + +[EmailAuthCredential](./auth.emailauthcredential.md#emailauthcredential_class) + +The auth provider credential. + +### Example 1 + + +```javascript +const authCredential = EmailAuthProvider.credential(email, password); +const userCredential = await signInWithCredential(auth, authCredential); + +``` + +### Example 2 + + +```javascript +const userCredential = await signInWithEmailAndPassword(auth, email, password); + +``` + +## EmailAuthProvider.credentialWithLink() + +Initialize an [AuthCredential](./auth.authcredential.md#authcredential_class) using an email and an email link after a sign in with email link operation. + +Signature: + +```typescript +static credentialWithLink(email: string, emailLink: string): EmailAuthCredential; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| email | string | Email address. | +| emailLink | string | Sign-in email link. | + +Returns: + +[EmailAuthCredential](./auth.emailauthcredential.md#emailauthcredential_class) + +- The auth provider credential. + +### Example 1 + + +```javascript +const authCredential = EmailAuthProvider.credentialWithLink(auth, email, emailLink); +const userCredential = await signInWithCredential(auth, authCredential); + +``` + +### Example 2 + + +```javascript +await sendSignInLinkToEmail(auth, email); +// Obtain emailLink from user. +const userCredential = await signInWithEmailLink(auth, email, emailLink); + +``` + diff --git a/docs-devsite/auth.emulatorconfig.md b/docs-devsite/auth.emulatorconfig.md new file mode 100644 index 00000000000..23f052c8dc4 --- /dev/null +++ b/docs-devsite/auth.emulatorconfig.md @@ -0,0 +1,70 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# EmulatorConfig interface +Configuration of Firebase Authentication Emulator. + +Signature: + +```typescript +export interface EmulatorConfig +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [host](./auth.emulatorconfig.md#emulatorconfighost) | string | The hostname of the emulator, which may be a domain ("localhost"), IPv4 address ("127.0.0.1") or quoted IPv6 address ("\[::1\]"). | +| [options](./auth.emulatorconfig.md#emulatorconfigoptions) | { readonly disableWarnings: boolean; } | The emulator-specific options. | +| [port](./auth.emulatorconfig.md#emulatorconfigport) | number \| null | The port of the emulator, or null if port isn't specified (i.e. protocol default). | +| [protocol](./auth.emulatorconfig.md#emulatorconfigprotocol) | string | The protocol used to communicate with the emulator ("http"/"https"). | + +## EmulatorConfig.host + +The hostname of the emulator, which may be a domain ("localhost"), IPv4 address ("127.0.0.1") or quoted IPv6 address ("\[::1\]"). + +Signature: + +```typescript +readonly host: string; +``` + +## EmulatorConfig.options + +The emulator-specific options. + +Signature: + +```typescript +readonly options: { + readonly disableWarnings: boolean; + }; +``` + +## EmulatorConfig.port + +The port of the emulator, or null if port isn't specified (i.e. protocol default). + +Signature: + +```typescript +readonly port: number | null; +``` + +## EmulatorConfig.protocol + +The protocol used to communicate with the emulator ("http"/"https"). + +Signature: + +```typescript +readonly protocol: string; +``` diff --git a/docs-devsite/auth.facebookauthprovider.md b/docs-devsite/auth.facebookauthprovider.md new file mode 100644 index 00000000000..71ac4eea79c --- /dev/null +++ b/docs-devsite/auth.facebookauthprovider.md @@ -0,0 +1,182 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FacebookAuthProvider class +Provider for generating an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).FACEBOOK. + +Signature: + +```typescript +export declare class FacebookAuthProvider extends BaseOAuthProvider +``` +Extends: BaseOAuthProvider + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)()](./auth.facebookauthprovider.md#facebookauthproviderconstructor) | | Constructs a new instance of the FacebookAuthProvider class | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [FACEBOOK\_SIGN\_IN\_METHOD](./auth.facebookauthprovider.md#facebookauthproviderfacebook_sign_in_method) | static | 'facebook.com' | Always set to [SignInMethod](./auth.md#signinmethod).FACEBOOK. | +| [PROVIDER\_ID](./auth.facebookauthprovider.md#facebookauthproviderprovider_id) | static | 'facebook.com' | Always set to [ProviderId](./auth.md#providerid).FACEBOOK. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [credential(accessToken)](./auth.facebookauthprovider.md#facebookauthprovidercredential) | static | Creates a credential for Facebook. | +| [credentialFromError(error)](./auth.facebookauthprovider.md#facebookauthprovidercredentialfromerror) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. | +| [credentialFromResult(userCredential)](./auth.facebookauthprovider.md#facebookauthprovidercredentialfromresult) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). | + +## FacebookAuthProvider.(constructor) + +Constructs a new instance of the `FacebookAuthProvider` class + +Signature: + +```typescript +constructor(); +``` + +## FacebookAuthProvider.FACEBOOK\_SIGN\_IN\_METHOD + +Always set to [SignInMethod](./auth.md#signinmethod).FACEBOOK. + +Signature: + +```typescript +static readonly FACEBOOK_SIGN_IN_METHOD: 'facebook.com'; +``` + +## FacebookAuthProvider.PROVIDER\_ID + +Always set to [ProviderId](./auth.md#providerid).FACEBOOK. + +Signature: + +```typescript +static readonly PROVIDER_ID: 'facebook.com'; +``` + +## FacebookAuthProvider.credential() + +Creates a credential for Facebook. + +Signature: + +```typescript +static credential(accessToken: string): OAuthCredential; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| accessToken | string | Facebook access token. | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) + +### Example + + +```javascript +// `event` from the Facebook auth.authResponseChange callback. +const credential = FacebookAuthProvider.credential(event.authResponse.accessToken); +const result = await signInWithCredential(credential); + +``` + +## FacebookAuthProvider.credentialFromError() + +Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. + +Signature: + +```typescript +static credentialFromError(error: FirebaseError): OAuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null + +## FacebookAuthProvider.credentialFromResult() + +Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). + +Signature: + +```typescript +static credentialFromResult(userCredential: UserCredential): OAuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null + +### Example 1 + + +```javascript +// Sign in using a redirect. +const provider = new FacebookAuthProvider(); +// Start a sign in process for an unauthenticated user. +provider.addScope('user_birthday'); +await signInWithRedirect(auth, provider); +// This will trigger a full page redirect away from your app + +// After returning from the redirect when your app initializes you can obtain the result +const result = await getRedirectResult(auth); +if (result) { + // This is the signed-in user + const user = result.user; + // This gives you a Facebook Access Token. + const credential = FacebookAuthProvider.credentialFromResult(result); + const token = credential.accessToken; +} + +``` + +### Example 2 + + +```javascript +// Sign in using a popup. +const provider = new FacebookAuthProvider(); +provider.addScope('user_birthday'); +const result = await signInWithPopup(auth, provider); + +// The signed-in user info. +const user = result.user; +// This gives you a Facebook Access Token. +const credential = FacebookAuthProvider.credentialFromResult(result); +const token = credential.accessToken; + +``` + diff --git a/docs-devsite/auth.githubauthprovider.md b/docs-devsite/auth.githubauthprovider.md new file mode 100644 index 00000000000..d2e04bc8125 --- /dev/null +++ b/docs-devsite/auth.githubauthprovider.md @@ -0,0 +1,174 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# GithubAuthProvider class +Provider for generating an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).GITHUB. + +GitHub requires an OAuth 2.0 redirect, so you can either handle the redirect directly, or use the [signInWithPopup()](./auth.md#signinwithpopup) handler: + +Signature: + +```typescript +export declare class GithubAuthProvider extends BaseOAuthProvider +``` +Extends: BaseOAuthProvider + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)()](./auth.githubauthprovider.md#githubauthproviderconstructor) | | Constructs a new instance of the GithubAuthProvider class | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [GITHUB\_SIGN\_IN\_METHOD](./auth.githubauthprovider.md#githubauthprovidergithub_sign_in_method) | static | 'github.com' | Always set to [SignInMethod](./auth.md#signinmethod).GITHUB. | +| [PROVIDER\_ID](./auth.githubauthprovider.md#githubauthproviderprovider_id) | static | 'github.com' | Always set to [ProviderId](./auth.md#providerid).GITHUB. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [credential(accessToken)](./auth.githubauthprovider.md#githubauthprovidercredential) | static | Creates a credential for Github. | +| [credentialFromError(error)](./auth.githubauthprovider.md#githubauthprovidercredentialfromerror) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. | +| [credentialFromResult(userCredential)](./auth.githubauthprovider.md#githubauthprovidercredentialfromresult) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). | + +## GithubAuthProvider.(constructor) + +Constructs a new instance of the `GithubAuthProvider` class + +Signature: + +```typescript +constructor(); +``` + +## GithubAuthProvider.GITHUB\_SIGN\_IN\_METHOD + +Always set to [SignInMethod](./auth.md#signinmethod).GITHUB. + +Signature: + +```typescript +static readonly GITHUB_SIGN_IN_METHOD: 'github.com'; +``` + +## GithubAuthProvider.PROVIDER\_ID + +Always set to [ProviderId](./auth.md#providerid).GITHUB. + +Signature: + +```typescript +static readonly PROVIDER_ID: 'github.com'; +``` + +## GithubAuthProvider.credential() + +Creates a credential for Github. + +Signature: + +```typescript +static credential(accessToken: string): OAuthCredential; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| accessToken | string | Github access token. | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) + +## GithubAuthProvider.credentialFromError() + +Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. + +Signature: + +```typescript +static credentialFromError(error: FirebaseError): OAuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null + +## GithubAuthProvider.credentialFromResult() + +Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). + +Signature: + +```typescript +static credentialFromResult(userCredential: UserCredential): OAuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null + +### Example 1 + + +```javascript +// Sign in using a redirect. +const provider = new GithubAuthProvider(); +// Start a sign in process for an unauthenticated user. +provider.addScope('repo'); +await signInWithRedirect(auth, provider); +// This will trigger a full page redirect away from your app + +// After returning from the redirect when your app initializes you can obtain the result +const result = await getRedirectResult(auth); +if (result) { + // This is the signed-in user + const user = result.user; + // This gives you a Github Access Token. + const credential = GithubAuthProvider.credentialFromResult(result); + const token = credential.accessToken; +} + +``` + +### Example 2 + + +```javascript +// Sign in using a popup. +const provider = new GithubAuthProvider(); +provider.addScope('repo'); +const result = await signInWithPopup(auth, provider); + +// The signed-in user info. +const user = result.user; +// This gives you a Github Access Token. +const credential = GithubAuthProvider.credentialFromResult(result); +const token = credential.accessToken; + +``` + diff --git a/docs-devsite/auth.googleauthprovider.md b/docs-devsite/auth.googleauthprovider.md new file mode 100644 index 00000000000..2e14c0ff88e --- /dev/null +++ b/docs-devsite/auth.googleauthprovider.md @@ -0,0 +1,185 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# GoogleAuthProvider class +Provider for generating an an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).GOOGLE. + +Signature: + +```typescript +export declare class GoogleAuthProvider extends BaseOAuthProvider +``` +Extends: BaseOAuthProvider + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)()](./auth.googleauthprovider.md#googleauthproviderconstructor) | | Constructs a new instance of the GoogleAuthProvider class | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [GOOGLE\_SIGN\_IN\_METHOD](./auth.googleauthprovider.md#googleauthprovidergoogle_sign_in_method) | static | 'google.com' | Always set to [SignInMethod](./auth.md#signinmethod).GOOGLE. | +| [PROVIDER\_ID](./auth.googleauthprovider.md#googleauthproviderprovider_id) | static | 'google.com' | Always set to [ProviderId](./auth.md#providerid).GOOGLE. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [credential(idToken, accessToken)](./auth.googleauthprovider.md#googleauthprovidercredential) | static | Creates a credential for Google. At least one of ID token and access token is required. | +| [credentialFromError(error)](./auth.googleauthprovider.md#googleauthprovidercredentialfromerror) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. | +| [credentialFromResult(userCredential)](./auth.googleauthprovider.md#googleauthprovidercredentialfromresult) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). | + +## GoogleAuthProvider.(constructor) + +Constructs a new instance of the `GoogleAuthProvider` class + +Signature: + +```typescript +constructor(); +``` + +## GoogleAuthProvider.GOOGLE\_SIGN\_IN\_METHOD + +Always set to [SignInMethod](./auth.md#signinmethod).GOOGLE. + +Signature: + +```typescript +static readonly GOOGLE_SIGN_IN_METHOD: 'google.com'; +``` + +## GoogleAuthProvider.PROVIDER\_ID + +Always set to [ProviderId](./auth.md#providerid).GOOGLE. + +Signature: + +```typescript +static readonly PROVIDER_ID: 'google.com'; +``` + +## GoogleAuthProvider.credential() + +Creates a credential for Google. At least one of ID token and access token is required. + +Signature: + +```typescript +static credential(idToken?: string | null, accessToken?: string | null): OAuthCredential; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| idToken | string \| null | Google ID token. | +| accessToken | string \| null | Google access token. | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) + +### Example + + +```javascript +// \`googleUser\` from the onsuccess Google Sign In callback. +const credential = GoogleAuthProvider.credential(googleUser.getAuthResponse().id_token); +const result = await signInWithCredential(credential); + +``` + +## GoogleAuthProvider.credentialFromError() + +Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. + +Signature: + +```typescript +static credentialFromError(error: FirebaseError): OAuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null + +## GoogleAuthProvider.credentialFromResult() + +Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). + +Signature: + +```typescript +static credentialFromResult(userCredential: UserCredential): OAuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null + +### Example 1 + + +```javascript +// Sign in using a redirect. +const provider = new GoogleAuthProvider(); +// Start a sign in process for an unauthenticated user. +provider.addScope('profile'); +provider.addScope('email'); +await signInWithRedirect(auth, provider); +// This will trigger a full page redirect away from your app + +// After returning from the redirect when your app initializes you can obtain the result +const result = await getRedirectResult(auth); +if (result) { + // This is the signed-in user + const user = result.user; + // This gives you a Google Access Token. + const credential = GoogleAuthProvider.credentialFromResult(result); + const token = credential.accessToken; +} + +``` + +### Example 2 + + +```javascript +// Sign in using a popup. +const provider = new GoogleAuthProvider(); +provider.addScope('profile'); +provider.addScope('email'); +const result = await signInWithPopup(auth, provider); + +// The signed-in user info. +const user = result.user; +// This gives you a Google Access Token. +const credential = GoogleAuthProvider.credentialFromResult(result); +const token = credential.accessToken; + +``` + diff --git a/docs-devsite/auth.idtokenresult.md b/docs-devsite/auth.idtokenresult.md new file mode 100644 index 00000000000..f000df924d9 --- /dev/null +++ b/docs-devsite/auth.idtokenresult.md @@ -0,0 +1,109 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# IdTokenResult interface +Interface representing ID token result obtained from [User.getIdTokenResult()](./auth.user.md#usergetidtokenresult). + +`IdTokenResult` contains the ID token JWT string and other helper properties for getting different data associated with the token as well as all the decoded payload claims. + +Note that these claims are not to be trusted as they are parsed client side. Only server side verification can guarantee the integrity of the token claims. + +Signature: + +```typescript +export interface IdTokenResult +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [authTime](./auth.idtokenresult.md#idtokenresultauthtime) | string | The authentication time formatted as a UTC string. | +| [claims](./auth.idtokenresult.md#idtokenresultclaims) | [ParsedToken](./auth.parsedtoken.md#parsedtoken_interface) | The entire payload claims of the ID token including the standard reserved claims as well as the custom claims. | +| [expirationTime](./auth.idtokenresult.md#idtokenresultexpirationtime) | string | The ID token expiration time formatted as a UTC string. | +| [issuedAtTime](./auth.idtokenresult.md#idtokenresultissuedattime) | string | The ID token issuance time formatted as a UTC string. | +| [signInProvider](./auth.idtokenresult.md#idtokenresultsigninprovider) | string \| null | The sign-in provider through which the ID token was obtained (anonymous, custom, phone, password, etc). | +| [signInSecondFactor](./auth.idtokenresult.md#idtokenresultsigninsecondfactor) | string \| null | The type of second factor associated with this session, provided the user was multi-factor authenticated (eg. phone, etc). | +| [token](./auth.idtokenresult.md#idtokenresulttoken) | string | The Firebase Auth ID token JWT string. | + +## IdTokenResult.authTime + +The authentication time formatted as a UTC string. + +This is the time the user authenticated (signed in) and not the time the token was refreshed. + +Signature: + +```typescript +authTime: string; +``` + +## IdTokenResult.claims + +The entire payload claims of the ID token including the standard reserved claims as well as the custom claims. + +Signature: + +```typescript +claims: ParsedToken; +``` + +## IdTokenResult.expirationTime + +The ID token expiration time formatted as a UTC string. + +Signature: + +```typescript +expirationTime: string; +``` + +## IdTokenResult.issuedAtTime + +The ID token issuance time formatted as a UTC string. + +Signature: + +```typescript +issuedAtTime: string; +``` + +## IdTokenResult.signInProvider + +The sign-in provider through which the ID token was obtained (anonymous, custom, phone, password, etc). + +Note, this does not map to provider IDs. + +Signature: + +```typescript +signInProvider: string | null; +``` + +## IdTokenResult.signInSecondFactor + +The type of second factor associated with this session, provided the user was multi-factor authenticated (eg. phone, etc). + +Signature: + +```typescript +signInSecondFactor: string | null; +``` + +## IdTokenResult.token + +The Firebase Auth ID token JWT string. + +Signature: + +```typescript +token: string; +``` diff --git a/docs-devsite/auth.md b/docs-devsite/auth.md new file mode 100644 index 00000000000..f0f9029c225 --- /dev/null +++ b/docs-devsite/auth.md @@ -0,0 +1,1992 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# auth package +Firebase Authentication + +## Functions + +| Function | Description | +| --- | --- | +| function(app...) | +| [getAuth(app)](./auth.md#getauth) | Returns the Auth instance associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). If no instance exists, initializes an Auth instance with platform-specific default dependencies. | +| [initializeAuth(app, deps)](./auth.md#initializeauth) | Initializes an [Auth](./auth.auth.md#auth_interface) instance with fine-grained control over [Dependencies](./auth.dependencies.md#dependencies_interface). | +| function(storage...) | +| [getReactNativePersistence(storage)](./auth.md#getreactnativepersistence) | Returns a persistence object that wraps AsyncStorage imported from react-native or @react-native-community/async-storage, and can be used in the persistence dependency field in [initializeAuth()](./auth.md#initializeauth). | +| function(auth...) | +| [applyActionCode(auth, oobCode)](./auth.md#applyactioncode) | Applies a verification code sent to the user by email or other out-of-band mechanism. | +| [beforeAuthStateChanged(auth, callback, onAbort)](./auth.md#beforeauthstatechanged) | Adds a blocking callback that runs before an auth state change sets a new user. | +| [checkActionCode(auth, oobCode)](./auth.md#checkactioncode) | Checks a verification code sent to the user by email or other out-of-band mechanism. | +| [confirmPasswordReset(auth, oobCode, newPassword)](./auth.md#confirmpasswordreset) | Completes the password reset process, given a confirmation code and new password. | +| [connectAuthEmulator(auth, url, options)](./auth.md#connectauthemulator) | Changes the [Auth](./auth.auth.md#auth_interface) instance to communicate with the Firebase Auth Emulator, instead of production Firebase Auth services. | +| [createUserWithEmailAndPassword(auth, email, password)](./auth.md#createuserwithemailandpassword) | Creates a new user account associated with the specified email address and password. | +| [fetchSignInMethodsForEmail(auth, email)](./auth.md#fetchsigninmethodsforemail) | Gets the list of possible sign in methods for the given email address. | +| [getMultiFactorResolver(auth, error)](./auth.md#getmultifactorresolver) | Provides a [MultiFactorResolver](./auth.multifactorresolver.md#multifactorresolver_interface) suitable for completion of a multi-factor flow. | +| [getRedirectResult(auth, resolver)](./auth.md#getredirectresult) | Returns a [UserCredential](./auth.usercredential.md#usercredential_interface) from the redirect-based sign-in flow. | +| [isSignInWithEmailLink(auth, emailLink)](./auth.md#issigninwithemaillink) | Checks if an incoming link is a sign-in with email link suitable for [signInWithEmailLink()](./auth.md#signinwithemaillink). | +| [onAuthStateChanged(auth, nextOrObserver, error, completed)](./auth.md#onauthstatechanged) | Adds an observer for changes to the user's sign-in state. | +| [onIdTokenChanged(auth, nextOrObserver, error, completed)](./auth.md#onidtokenchanged) | Adds an observer for changes to the signed-in user's ID token. | +| [sendPasswordResetEmail(auth, email, actionCodeSettings)](./auth.md#sendpasswordresetemail) | Sends a password reset email to the given email address. | +| [sendSignInLinkToEmail(auth, email, actionCodeSettings)](./auth.md#sendsigninlinktoemail) | Sends a sign-in email link to the user with the specified email. | +| [setPersistence(auth, persistence)](./auth.md#setpersistence) | Changes the type of persistence on the [Auth](./auth.auth.md#auth_interface) instance for the currently saved Auth session and applies this type of persistence for future sign-in requests, including sign-in with redirect requests. | +| [signInAnonymously(auth)](./auth.md#signinanonymously) | Asynchronously signs in as an anonymous user. | +| [signInWithCredential(auth, credential)](./auth.md#signinwithcredential) | Asynchronously signs in with the given credentials. | +| [signInWithCustomToken(auth, customToken)](./auth.md#signinwithcustomtoken) | Asynchronously signs in using a custom token. | +| [signInWithEmailAndPassword(auth, email, password)](./auth.md#signinwithemailandpassword) | Asynchronously signs in using an email and password. | +| [signInWithEmailLink(auth, email, emailLink)](./auth.md#signinwithemaillink) | Asynchronously signs in using an email and sign-in email link. | +| [signInWithPhoneNumber(auth, phoneNumber, appVerifier)](./auth.md#signinwithphonenumber) | Asynchronously signs in using a phone number. | +| [signInWithPopup(auth, provider, resolver)](./auth.md#signinwithpopup) | Authenticates a Firebase client using a popup-based OAuth authentication flow. | +| [signInWithRedirect(auth, provider, resolver)](./auth.md#signinwithredirect) | Authenticates a Firebase client using a full-page redirect flow. | +| [signOut(auth)](./auth.md#signout) | Signs out the current user. | +| [updateCurrentUser(auth, user)](./auth.md#updatecurrentuser) | Asynchronously sets the provided user as [Auth.currentUser](./auth.auth.md#authcurrentuser) on the [Auth](./auth.auth.md#auth_interface) instance. | +| [useDeviceLanguage(auth)](./auth.md#usedevicelanguage) | Sets the current language to the default device/browser preference. | +| [verifyPasswordResetCode(auth, code)](./auth.md#verifypasswordresetcode) | Checks a password reset code sent to the user by email or other out-of-band mechanism. | +| function(link...) | +| [parseActionCodeURL(link)](./auth.md#parseactioncodeurl) | Parses the email action link string and returns an [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) if the link is valid, otherwise returns null. | +| function(user...) | +| [deleteUser(user)](./auth.md#deleteuser) | Deletes and signs out the user. | +| [getIdToken(user, forceRefresh)](./auth.md#getidtoken) | Returns a JSON Web Token (JWT) used to identify the user to a Firebase service. | +| [getIdTokenResult(user, forceRefresh)](./auth.md#getidtokenresult) | Returns a deserialized JSON Web Token (JWT) used to identitfy the user to a Firebase service. | +| [linkWithCredential(user, credential)](./auth.md#linkwithcredential) | Links the user account with the given credentials. | +| [linkWithPhoneNumber(user, phoneNumber, appVerifier)](./auth.md#linkwithphonenumber) | Links the user account with the given phone number. | +| [linkWithPopup(user, provider, resolver)](./auth.md#linkwithpopup) | Links the authenticated provider to the user account using a pop-up based OAuth flow. | +| [linkWithRedirect(user, provider, resolver)](./auth.md#linkwithredirect) | Links the [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) to the user account using a full-page redirect flow. | +| [multiFactor(user)](./auth.md#multifactor) | The [MultiFactorUser](./auth.multifactoruser.md#multifactoruser_interface) corresponding to the user. | +| [reauthenticateWithCredential(user, credential)](./auth.md#reauthenticatewithcredential) | Re-authenticates a user using a fresh credential. | +| [reauthenticateWithPhoneNumber(user, phoneNumber, appVerifier)](./auth.md#reauthenticatewithphonenumber) | Re-authenticates a user using a fresh phone credential. | +| [reauthenticateWithPopup(user, provider, resolver)](./auth.md#reauthenticatewithpopup) | Reauthenticates the current user with the specified [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) using a pop-up based OAuth flow. | +| [reauthenticateWithRedirect(user, provider, resolver)](./auth.md#reauthenticatewithredirect) | Reauthenticates the current user with the specified [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) using a full-page redirect flow. | +| [reload(user)](./auth.md#reload) | Reloads user account data, if signed in. | +| [sendEmailVerification(user, actionCodeSettings)](./auth.md#sendemailverification) | Sends a verification email to a user. | +| [unlink(user, providerId)](./auth.md#unlink) | Unlinks a provider from a user account. | +| [updateEmail(user, newEmail)](./auth.md#updateemail) | Updates the user's email address. | +| [updatePassword(user, newPassword)](./auth.md#updatepassword) | Updates the user's password. | +| [updatePhoneNumber(user, credential)](./auth.md#updatephonenumber) | Updates the user's phone number. | +| [updateProfile(user, { displayName, photoURL: photoUrl })](./auth.md#updateprofile) | Updates a user's profile data. | +| [verifyBeforeUpdateEmail(user, newEmail, actionCodeSettings)](./auth.md#verifybeforeupdateemail) | Sends a verification email to a new email address. | +| function(userCredential...) | +| [getAdditionalUserInfo(userCredential)](./auth.md#getadditionaluserinfo) | Extracts provider specific [AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface) for the given credential. | + +## Classes + +| Class | Description | +| --- | --- | +| [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) | A utility class to parse email action URLs such as password reset, email verification, email link sign in, etc. | +| [AuthCredential](./auth.authcredential.md#authcredential_class) | Interface that represents the credentials returned by an [AuthProvider](./auth.authprovider.md#authprovider_interface). | +| [EmailAuthCredential](./auth.emailauthcredential.md#emailauthcredential_class) | Interface that represents the credentials returned by [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) for [ProviderId](./auth.md#providerid).PASSWORD | +| [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) | Provider for generating [EmailAuthCredential](./auth.emailauthcredential.md#emailauthcredential_class). | +| [FacebookAuthProvider](./auth.facebookauthprovider.md#facebookauthprovider_class) | Provider for generating an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).FACEBOOK. | +| [GithubAuthProvider](./auth.githubauthprovider.md#githubauthprovider_class) | Provider for generating an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).GITHUB. | +| [GoogleAuthProvider](./auth.googleauthprovider.md#googleauthprovider_class) | Provider for generating an an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).GOOGLE. | +| [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) | Represents the OAuth credentials returned by an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). | +| [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) | Provider for generating generic [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). | +| [PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class) | Represents the credentials returned by [PhoneAuthProvider](./auth.phoneauthprovider.md#phoneauthprovider_class). | +| [PhoneAuthProvider](./auth.phoneauthprovider.md#phoneauthprovider_class) | Provider for generating an [PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class). | +| [PhoneMultiFactorGenerator](./auth.phonemultifactorgenerator.md#phonemultifactorgenerator_class) | Provider for generating a [PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface). | +| [RecaptchaVerifier](./auth.recaptchaverifier.md#recaptchaverifier_class) | An [reCAPTCHA](https://www.google.com/recaptcha/)-based application verifier. | +| [SAMLAuthProvider](./auth.samlauthprovider.md#samlauthprovider_class) | An [AuthProvider](./auth.authprovider.md#authprovider_interface) for SAML. | +| [TwitterAuthProvider](./auth.twitterauthprovider.md#twitterauthprovider_class) | Provider for generating an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).TWITTER. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [ActionCodeInfo](./auth.actioncodeinfo.md#actioncodeinfo_interface) | A response from [checkActionCode()](./auth.md#checkactioncode). | +| [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface) | An interface that defines the required continue/state URL with optional Android and iOS bundle identifiers. | +| [AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface) | A structure containing additional user information from a federated identity provider. | +| [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) | A verifier for domain verification and abuse prevention. | +| [Auth](./auth.auth.md#auth_interface) | Interface representing Firebase Auth service. | +| [AuthError](./auth.autherror.md#autherror_interface) | Interface for an Auth error. | +| [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) | A mapping of error codes to error messages. | +| [AuthProvider](./auth.authprovider.md#authprovider_interface) | Interface that represents an auth provider, used to facilitate creating [AuthCredential](./auth.authcredential.md#authcredential_class). | +| [AuthSettings](./auth.authsettings.md#authsettings_interface) | Interface representing an [Auth](./auth.auth.md#auth_interface) instance's settings. | +| [Config](./auth.config.md#config_interface) | Interface representing the Auth config. | +| [ConfirmationResult](./auth.confirmationresult.md#confirmationresult_interface) | A result from a phone number sign-in, link, or reauthenticate call. | +| [Dependencies](./auth.dependencies.md#dependencies_interface) | The dependencies that can be used to initialize an [Auth](./auth.auth.md#auth_interface) instance. | +| [EmulatorConfig](./auth.emulatorconfig.md#emulatorconfig_interface) | Configuration of Firebase Authentication Emulator. | +| [IdTokenResult](./auth.idtokenresult.md#idtokenresult_interface) | Interface representing ID token result obtained from [User.getIdTokenResult()](./auth.user.md#usergetidtokenresult). | +| [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) | The base class for asserting ownership of a second factor. | +| [MultiFactorError](./auth.multifactorerror.md#multifactorerror_interface) | The error thrown when the user needs to provide a second factor to sign in successfully. | +| [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) | A structure containing the information of a second factor entity. | +| [MultiFactorResolver](./auth.multifactorresolver.md#multifactorresolver_interface) | The class used to facilitate recovery from [MultiFactorError](./auth.multifactorerror.md#multifactorerror_interface) when a user needs to provide a second factor to sign in. | +| [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) | An interface defining the multi-factor session object used for enrolling a second factor on a user or helping sign in an enrolled user with a second factor. | +| [MultiFactorUser](./auth.multifactoruser.md#multifactoruser_interface) | An interface that defines the multi-factor related properties and operations pertaining to a [User](./auth.user.md#user_interface). | +| [OAuthCredentialOptions](./auth.oauthcredentialoptions.md#oauthcredentialoptions_interface) | Defines the options for initializing an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). | +| [ParsedToken](./auth.parsedtoken.md#parsedtoken_interface) | Interface representing a parsed ID token. | +| [Persistence](./auth.persistence.md#persistence_interface) | An interface covering the possible persistence mechanism types. | +| [PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface) | The class for asserting ownership of a phone second factor. Provided by [PhoneMultiFactorGenerator.assertion()](./auth.phonemultifactorgenerator.md#phonemultifactorgeneratorassertion). | +| [PhoneMultiFactorEnrollInfoOptions](./auth.phonemultifactorenrollinfooptions.md#phonemultifactorenrollinfooptions_interface) | Options used for enrolling a second factor. | +| [PhoneMultiFactorInfo](./auth.phonemultifactorinfo.md#phonemultifactorinfo_interface) | The subclass of the [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) interface for phone number second factors. The factorId of this second factor is [FactorId](./auth.md#factorid).PHONE. | +| [PhoneMultiFactorSignInInfoOptions](./auth.phonemultifactorsignininfooptions.md#phonemultifactorsignininfooptions_interface) | Options used for signing in with a second factor. | +| [PhoneSingleFactorInfoOptions](./auth.phonesinglefactorinfooptions.md#phonesinglefactorinfooptions_interface) | Options used for single-factor sign-in. | +| [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | A resolver used for handling DOM specific operations like [signInWithPopup()](./auth.md#signinwithpopup) or [signInWithRedirect()](./auth.md#signinwithredirect). | +| [ReactNativeAsyncStorage](./auth.reactnativeasyncstorage.md#reactnativeasyncstorage_interface) | Interface for a supplied AsyncStorage. | +| [RecaptchaParameters](./auth.recaptchaparameters.md#recaptchaparameters_interface) | Interface representing reCAPTCHA parameters.See the \[reCAPTCHA docs\](https://developers.google.com/recaptcha/docs/display\#render\_param) for the list of accepted parameters. All parameters are accepted except for sitekey: Firebase Auth provisions a reCAPTCHA for each project and will configure the site key upon rendering.For an invisible reCAPTCHA, set the size key to invisible. | +| [User](./auth.user.md#user_interface) | A user account. | +| [UserCredential](./auth.usercredential.md#usercredential_interface) | A structure containing a [User](./auth.user.md#user_interface), the [OperationType](./auth.md#operationtype), and the provider ID. | +| [UserInfo](./auth.userinfo.md#userinfo_interface) | User profile information, visible only to the Firebase project's apps. | +| [UserMetadata](./auth.usermetadata.md#usermetadata_interface) | Interface representing a user's metadata. | + +## Variables + +| Variable | Description | +| --- | --- | +| [ActionCodeOperation](./auth.md#actioncodeoperation) | An enumeration of the possible email action types. | +| [AuthErrorCodes](./auth.md#autherrorcodes) | A map of potential Auth error codes, for easier comparison with errors thrown by the SDK. | +| [browserLocalPersistence](./auth.md#browserlocalpersistence) | An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type LOCAL using localStorage for the underlying storage. | +| [browserPopupRedirectResolver](./auth.md#browserpopupredirectresolver) | An implementation of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) suitable for browser based applications. | +| [browserSessionPersistence](./auth.md#browsersessionpersistence) | An implementation of [Persistence](./auth.persistence.md#persistence_interface) of SESSION using sessionStorage for the underlying storage. | +| [cordovaPopupRedirectResolver](./auth.md#cordovapopupredirectresolver) | An implementation of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) suitable for Cordova based applications. | +| [debugErrorMap](./auth.md#debugerrormap) | A verbose error map with detailed descriptions for most error codes.See discussion at [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) | +| [FactorId](./auth.md#factorid) | An enum of factors that may be used for multifactor authentication. | +| [indexedDBLocalPersistence](./auth.md#indexeddblocalpersistence) | An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type LOCAL using indexedDB for the underlying storage. | +| [inMemoryPersistence](./auth.md#inmemorypersistence) | An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type 'NONE'. | +| [OperationType](./auth.md#operationtype) | Enumeration of supported operation types. | +| [prodErrorMap](./auth.md#proderrormap) | A minimal error map with all verbose error messages stripped.See discussion at [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) | +| [ProviderId](./auth.md#providerid) | Enumeration of supported providers. | +| [reactNativeLocalPersistence](./auth.md#reactnativelocalpersistence) | An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type 'LOCAL' for use in React Native environments. | +| [SignInMethod](./auth.md#signinmethod) | Enumeration of supported sign-in methods. | + +## Type Aliases + +| Type Alias | Description | +| --- | --- | +| [CustomParameters](./auth.md#customparameters) | Map of OAuth Custom Parameters. | +| [NextOrObserver](./auth.md#nextorobserver) | Type definition for an event callback. | +| [PhoneInfoOptions](./auth.md#phoneinfooptions) | The information required to verify the ownership of a phone number. | +| [UserProfile](./auth.md#userprofile) | User profile used in [AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface). | + +## getAuth() + +Returns the Auth instance associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). If no instance exists, initializes an Auth instance with platform-specific default dependencies. + +Signature: + +```typescript +export declare function getAuth(app?: FirebaseApp): Auth; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The Firebase App. | + +Returns: + +[Auth](./auth.auth.md#auth_interface) + +## initializeAuth() + +Initializes an [Auth](./auth.auth.md#auth_interface) instance with fine-grained control over [Dependencies](./auth.dependencies.md#dependencies_interface). + +This function allows more control over the [Auth](./auth.auth.md#auth_interface) instance than [getAuth()](./auth.md#getauth). `getAuth` uses platform-specific defaults to supply the [Dependencies](./auth.dependencies.md#dependencies_interface). In general, `getAuth` is the easiest way to initialize Auth and works for most use cases. Use `initializeAuth` if you need control over which persistence layer is used, or to minimize bundle size if you're not using either `signInWithPopup` or `signInWithRedirect`. + +For example, if your app only uses anonymous accounts and you only want accounts saved for the current session, initialize `Auth` with: + +```js +const auth = initializeAuth(app, { + persistence: browserSessionPersistence, + popupRedirectResolver: undefined, +}); + +``` + +Signature: + +```typescript +export declare function initializeAuth(app: FirebaseApp, deps?: Dependencies): Auth; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | | +| deps | [Dependencies](./auth.dependencies.md#dependencies_interface) | | + +Returns: + +[Auth](./auth.auth.md#auth_interface) + +## getReactNativePersistence() + +Returns a persistence object that wraps `AsyncStorage` imported from `react-native` or `@react-native-community/async-storage`, and can be used in the persistence dependency field in [initializeAuth()](./auth.md#initializeauth). + +Signature: + +```typescript +export declare function getReactNativePersistence(storage: ReactNativeAsyncStorage): Persistence; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| storage | [ReactNativeAsyncStorage](./auth.reactnativeasyncstorage.md#reactnativeasyncstorage_interface) | | + +Returns: + +[Persistence](./auth.persistence.md#persistence_interface) + +## applyActionCode() + +Applies a verification code sent to the user by email or other out-of-band mechanism. + +Signature: + +```typescript +export declare function applyActionCode(auth: Auth, oobCode: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| oobCode | string | A verification code sent to the user. | + +Returns: + +Promise<void> + +## beforeAuthStateChanged() + +Adds a blocking callback that runs before an auth state change sets a new user. + +Signature: + +```typescript +export declare function beforeAuthStateChanged(auth: Auth, callback: (user: User | null) => void | Promise, onAbort?: () => void): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| callback | (user: [User](./auth.user.md#user_interface) \| null) => void \| Promise<void> | callback triggered before new user value is set. If this throws, it blocks the user from being set. | +| onAbort | () => void | callback triggered if a later beforeAuthStateChanged() callback throws, allowing you to undo any side effects. | + +Returns: + +[Unsubscribe](./util.md#unsubscribe) + +## checkActionCode() + +Checks a verification code sent to the user by email or other out-of-band mechanism. + +Signature: + +```typescript +export declare function checkActionCode(auth: Auth, oobCode: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| oobCode | string | A verification code sent to the user. | + +Returns: + +Promise<[ActionCodeInfo](./auth.actioncodeinfo.md#actioncodeinfo_interface)> + +metadata about the code. + +## confirmPasswordReset() + +Completes the password reset process, given a confirmation code and new password. + +Signature: + +```typescript +export declare function confirmPasswordReset(auth: Auth, oobCode: string, newPassword: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| oobCode | string | A confirmation code sent to the user. | +| newPassword | string | The new password. | + +Returns: + +Promise<void> + +## connectAuthEmulator() + +Changes the [Auth](./auth.auth.md#auth_interface) instance to communicate with the Firebase Auth Emulator, instead of production Firebase Auth services. + +This must be called synchronously immediately following the first call to [initializeAuth()](./auth.md#initializeauth). Do not use with production credentials as emulator traffic is not encrypted. + +Signature: + +```typescript +export declare function connectAuthEmulator(auth: Auth, url: string, options?: { + disableWarnings: boolean; +}): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| url | string | The URL at which the emulator is running (eg, 'http://localhost:9099'). | +| options | { disableWarnings: boolean; } | Optional. options.disableWarnings defaults to false. Set it to true to disable the warning banner attached to the DOM. | + +Returns: + +void + +### Example + + +```javascript +connectAuthEmulator(auth, 'http://127.0.0.1:9099', { disableWarnings: true }); + +``` + +## createUserWithEmailAndPassword() + +Creates a new user account associated with the specified email address and password. + +On successful creation of the user account, this user will also be signed in to your application. + +User account creation can fail if the account already exists or the password is invalid. + +Note: The email address acts as a unique identifier for the user and enables an email-based password reset. This function will create a new user account and set the initial user password. + +Signature: + +```typescript +export declare function createUserWithEmailAndPassword(auth: Auth, email: string, password: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| email | string | The user's email address. | +| password | string | The user's chosen password. | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> + +## fetchSignInMethodsForEmail() + +Gets the list of possible sign in methods for the given email address. + +This is useful to differentiate methods of sign-in for the same provider, eg. [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) which has 2 methods of sign-in, [SignInMethod](./auth.md#signinmethod).EMAIL\_PASSWORD and [SignInMethod](./auth.md#signinmethod).EMAIL\_LINK. + +Signature: + +```typescript +export declare function fetchSignInMethodsForEmail(auth: Auth, email: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| email | string | The user's email address. | + +Returns: + +Promise<string\[\]> + +## getMultiFactorResolver() + +Provides a [MultiFactorResolver](./auth.multifactorresolver.md#multifactorresolver_interface) suitable for completion of a multi-factor flow. + +Signature: + +```typescript +export declare function getMultiFactorResolver(auth: Auth, error: MultiFactorError): MultiFactorResolver; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| error | [MultiFactorError](./auth.multifactorerror.md#multifactorerror_interface) | The [MultiFactorError](./auth.multifactorerror.md#multifactorerror_interface) raised during a sign-in, or reauthentication operation. | + +Returns: + +[MultiFactorResolver](./auth.multifactorresolver.md#multifactorresolver_interface) + +## getRedirectResult() + +Returns a [UserCredential](./auth.usercredential.md#usercredential_interface) from the redirect-based sign-in flow. + +If sign-in succeeded, returns the signed in user. If sign-in was unsuccessful, fails with an error. If no redirect operation was called, returns `null`. + +Signature: + +```typescript +export declare function getRedirectResult(auth: Auth, resolver?: PopupRedirectResolver): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface) \| null> + +### Example + + +```javascript +// Sign in using a redirect. +const provider = new FacebookAuthProvider(); +// You can add additional scopes to the provider: +provider.addScope('user_birthday'); +// Start a sign in process for an unauthenticated user. +await signInWithRedirect(auth, provider); +// This will trigger a full page redirect away from your app + +// After returning from the redirect when your app initializes you can obtain the result +const result = await getRedirectResult(auth); +if (result) { + // This is the signed-in user + const user = result.user; + // This gives you a Facebook Access Token. + const credential = provider.credentialFromResult(auth, result); + const token = credential.accessToken; +} +// As this API can be used for sign-in, linking and reauthentication, +// check the operationType to determine what triggered this redirect +// operation. +const operationType = result.operationType; + +``` + +## isSignInWithEmailLink() + +Checks if an incoming link is a sign-in with email link suitable for [signInWithEmailLink()](./auth.md#signinwithemaillink). + +Signature: + +```typescript +export declare function isSignInWithEmailLink(auth: Auth, emailLink: string): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| emailLink | string | The link sent to the user's email address. | + +Returns: + +boolean + +## onAuthStateChanged() + +Adds an observer for changes to the user's sign-in state. + +To keep the old behavior, see [onIdTokenChanged()](./auth.md#onidtokenchanged). + +Signature: + +```typescript +export declare function onAuthStateChanged(auth: Auth, nextOrObserver: NextOrObserver, error?: ErrorFn, completed?: CompleteFn): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| nextOrObserver | [NextOrObserver](./auth.md#nextorobserver)<[User](./auth.user.md#user_interface)> | callback triggered on change. | +| error | [ErrorFn](./util.md#errorfn) | Deprecated. This callback is never triggered. Errors on signing in/out can be caught in promises returned from sign-in/sign-out functions. | +| completed | [CompleteFn](./util.md#completefn) | Deprecated. This callback is never triggered. | + +Returns: + +[Unsubscribe](./util.md#unsubscribe) + +## onIdTokenChanged() + +Adds an observer for changes to the signed-in user's ID token. + +This includes sign-in, sign-out, and token refresh events. + +Signature: + +```typescript +export declare function onIdTokenChanged(auth: Auth, nextOrObserver: NextOrObserver, error?: ErrorFn, completed?: CompleteFn): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| nextOrObserver | [NextOrObserver](./auth.md#nextorobserver)<[User](./auth.user.md#user_interface)> | callback triggered on change. | +| error | [ErrorFn](./util.md#errorfn) | Deprecated. This callback is never triggered. Errors on signing in/out can be caught in promises returned from sign-in/sign-out functions. | +| completed | [CompleteFn](./util.md#completefn) | Deprecated. This callback is never triggered. | + +Returns: + +[Unsubscribe](./util.md#unsubscribe) + +## sendPasswordResetEmail() + +Sends a password reset email to the given email address. + +To complete the password reset, call [confirmPasswordReset()](./auth.md#confirmpasswordreset) with the code supplied in the email sent to the user, along with the new password specified by the user. + +Signature: + +```typescript +export declare function sendPasswordResetEmail(auth: Auth, email: string, actionCodeSettings?: ActionCodeSettings): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| email | string | The user's email address. | +| actionCodeSettings | [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface) | The [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface). | + +Returns: + +Promise<void> + +### Example + + +```javascript +const actionCodeSettings = { + url: 'https://www.example.com/?email=user@example.com', + iOS: { + bundleId: 'com.example.ios' + }, + android: { + packageName: 'com.example.android', + installApp: true, + minimumVersion: '12' + }, + handleCodeInApp: true +}; +await sendPasswordResetEmail(auth, 'user@example.com', actionCodeSettings); +// Obtain code from user. +await confirmPasswordReset('user@example.com', code); + +``` + +## sendSignInLinkToEmail() + +Sends a sign-in email link to the user with the specified email. + +The sign-in operation has to always be completed in the app unlike other out of band email actions (password reset and email verifications). This is because, at the end of the flow, the user is expected to be signed in and their Auth state persisted within the app. + +To complete sign in with the email link, call [signInWithEmailLink()](./auth.md#signinwithemaillink) with the email address and the email link supplied in the email sent to the user. + +Signature: + +```typescript +export declare function sendSignInLinkToEmail(auth: Auth, email: string, actionCodeSettings: ActionCodeSettings): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | | +| email | string | The user's email address. | +| actionCodeSettings | [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface) | The [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface). | + +Returns: + +Promise<void> + +### Example + + +```javascript +const actionCodeSettings = { + url: 'https://www.example.com/?email=user@example.com', + iOS: { + bundleId: 'com.example.ios' + }, + android: { + packageName: 'com.example.android', + installApp: true, + minimumVersion: '12' + }, + handleCodeInApp: true +}; +await sendSignInLinkToEmail(auth, 'user@example.com', actionCodeSettings); +// Obtain emailLink from the user. +if(isSignInWithEmailLink(auth, emailLink)) { + await signInWithEmailLink(auth, 'user@example.com', emailLink); +} + +``` + +## setPersistence() + +Changes the type of persistence on the [Auth](./auth.auth.md#auth_interface) instance for the currently saved `Auth` session and applies this type of persistence for future sign-in requests, including sign-in with redirect requests. + +This makes it easy for a user signing in to specify whether their session should be remembered or not. It also makes it easier to never persist the `Auth` state for applications that are shared by other users or have sensitive data. + +Signature: + +```typescript +export declare function setPersistence(auth: Auth, persistence: Persistence): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| persistence | [Persistence](./auth.persistence.md#persistence_interface) | The [Persistence](./auth.persistence.md#persistence_interface) to use. | + +Returns: + +Promise<void> + +A `Promise` that resolves once the persistence change has completed + +### Example + + +```javascript +setPersistence(auth, browserSessionPersistence); + +``` + +## signInAnonymously() + +Asynchronously signs in as an anonymous user. + +If there is already an anonymous user signed in, that user will be returned; otherwise, a new anonymous user identity will be created and returned. + +Signature: + +```typescript +export declare function signInAnonymously(auth: Auth): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> + +## signInWithCredential() + +Asynchronously signs in with the given credentials. + +An [AuthProvider](./auth.authprovider.md#authprovider_interface) can be used to generate the credential. + +Signature: + +```typescript +export declare function signInWithCredential(auth: Auth, credential: AuthCredential): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| credential | [AuthCredential](./auth.authcredential.md#authcredential_class) | The auth credential. | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> + +## signInWithCustomToken() + +Asynchronously signs in using a custom token. + +Custom tokens are used to integrate Firebase Auth with existing auth systems, and must be generated by an auth backend using the [createCustomToken](https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#createcustomtoken) method in the [Admin SDK](https://firebase.google.com/docs/auth/admin) . + +Fails with an error if the token is invalid, expired, or not accepted by the Firebase Auth service. + +Signature: + +```typescript +export declare function signInWithCustomToken(auth: Auth, customToken: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| customToken | string | The custom token to sign in with. | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> + +## signInWithEmailAndPassword() + +Asynchronously signs in using an email and password. + +Fails with an error if the email address and password do not match. + +Note: The user's password is NOT the password used to access the user's email account. The email address serves as a unique identifier for the user, and the password is used to access the user's account in your Firebase project. See also: [createUserWithEmailAndPassword()](./auth.md#createuserwithemailandpassword). + +Signature: + +```typescript +export declare function signInWithEmailAndPassword(auth: Auth, email: string, password: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| email | string | The users email address. | +| password | string | The users password. | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> + +## signInWithEmailLink() + +Asynchronously signs in using an email and sign-in email link. + +If no link is passed, the link is inferred from the current URL. + +Fails with an error if the email address is invalid or OTP in email link expires. + +Note: Confirm the link is a sign-in email link before calling this method firebase.auth.Auth.isSignInWithEmailLink. + +Signature: + +```typescript +export declare function signInWithEmailLink(auth: Auth, email: string, emailLink?: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| email | string | The user's email address. | +| emailLink | string | The link sent to the user's email address. | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> + +### Example + + +```javascript +const actionCodeSettings = { + url: 'https://www.example.com/?email=user@example.com', + iOS: { + bundleId: 'com.example.ios' + }, + android: { + packageName: 'com.example.android', + installApp: true, + minimumVersion: '12' + }, + handleCodeInApp: true +}; +await sendSignInLinkToEmail(auth, 'user@example.com', actionCodeSettings); +// Obtain emailLink from the user. +if(isSignInWithEmailLink(auth, emailLink)) { + await signInWithEmailLink(auth, 'user@example.com', emailLink); +} + +``` + +## signInWithPhoneNumber() + +Asynchronously signs in using a phone number. + +This method sends a code via SMS to the given phone number, and returns a [ConfirmationResult](./auth.confirmationresult.md#confirmationresult_interface). After the user provides the code sent to their phone, call [ConfirmationResult.confirm()](./auth.confirmationresult.md#confirmationresultconfirm) with the code to sign the user in. + +For abuse prevention, this method also requires a [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface). This SDK includes a reCAPTCHA-based implementation, [RecaptchaVerifier](./auth.recaptchaverifier.md#recaptchaverifier_class). This function can work on other platforms that do not support the [RecaptchaVerifier](./auth.recaptchaverifier.md#recaptchaverifier_class) (like React Native), but you need to use a third-party [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) implementation. + +Signature: + +```typescript +export declare function signInWithPhoneNumber(auth: Auth, phoneNumber: string, appVerifier: ApplicationVerifier): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| phoneNumber | string | The user's phone number in E.164 format (e.g. +16505550101). | +| appVerifier | [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) | The [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface). | + +Returns: + +Promise<[ConfirmationResult](./auth.confirmationresult.md#confirmationresult_interface)> + +### Example + + +```javascript +// 'recaptcha-container' is the ID of an element in the DOM. +const applicationVerifier = new firebase.auth.RecaptchaVerifier('recaptcha-container'); +const confirmationResult = await signInWithPhoneNumber(auth, phoneNumber, applicationVerifier); +// Obtain a verificationCode from the user. +const credential = await confirmationResult.confirm(verificationCode); + +``` + +## signInWithPopup() + +Authenticates a Firebase client using a popup-based OAuth authentication flow. + +If succeeds, returns the signed in user along with the provider's credential. If sign in was unsuccessful, returns an error object containing additional information about the error. + +Signature: + +```typescript +export declare function signInWithPopup(auth: Auth, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | +| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> + +### Example + + +```javascript +// Sign in using a popup. +const provider = new FacebookAuthProvider(); +const result = await signInWithPopup(auth, provider); + +// The signed-in user info. +const user = result.user; +// This gives you a Facebook Access Token. +const credential = provider.credentialFromResult(auth, result); +const token = credential.accessToken; + +``` + +## signInWithRedirect() + +Authenticates a Firebase client using a full-page redirect flow. + +To handle the results and errors for this operation, refer to [getRedirectResult()](./auth.md#getredirectresult). Follow the [best practices](https://firebase.google.com/docs/auth/web/redirect-best-practices) when using [signInWithRedirect()](./auth.md#signinwithredirect). + +Signature: + +```typescript +export declare function signInWithRedirect(auth: Auth, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | +| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | + +Returns: + +Promise<never> + +### Example + + +```javascript +// Sign in using a redirect. +const provider = new FacebookAuthProvider(); +// You can add additional scopes to the provider: +provider.addScope('user_birthday'); +// Start a sign in process for an unauthenticated user. +await signInWithRedirect(auth, provider); +// This will trigger a full page redirect away from your app + +// After returning from the redirect when your app initializes you can obtain the result +const result = await getRedirectResult(auth); +if (result) { + // This is the signed-in user + const user = result.user; + // This gives you a Facebook Access Token. + const credential = provider.credentialFromResult(auth, result); + const token = credential.accessToken; +} +// As this API can be used for sign-in, linking and reauthentication, +// check the operationType to determine what triggered this redirect +// operation. +const operationType = result.operationType; + +``` + +## signOut() + +Signs out the current user. + +Signature: + +```typescript +export declare function signOut(auth: Auth): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | + +Returns: + +Promise<void> + +## updateCurrentUser() + +Asynchronously sets the provided user as [Auth.currentUser](./auth.auth.md#authcurrentuser) on the [Auth](./auth.auth.md#auth_interface) instance. + +A new instance copy of the user provided will be made and set as currentUser. + +This will trigger [onAuthStateChanged()](./auth.md#onauthstatechanged) and [onIdTokenChanged()](./auth.md#onidtokenchanged) listeners like other sign in methods. + +The operation fails with an error if the user to be updated belongs to a different Firebase project. + +Signature: + +```typescript +export declare function updateCurrentUser(auth: Auth, user: User | null): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| user | [User](./auth.user.md#user_interface) \| null | The new [User](./auth.user.md#user_interface). | + +Returns: + +Promise<void> + +## useDeviceLanguage() + +Sets the current language to the default device/browser preference. + +Signature: + +```typescript +export declare function useDeviceLanguage(auth: Auth): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | + +Returns: + +void + +## verifyPasswordResetCode() + +Checks a password reset code sent to the user by email or other out-of-band mechanism. + +Signature: + +```typescript +export declare function verifyPasswordResetCode(auth: Auth, code: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The [Auth](./auth.auth.md#auth_interface) instance. | +| code | string | A verification code sent to the user. | + +Returns: + +Promise<string> + +the user's email address if valid. + +## parseActionCodeURL() + +Parses the email action link string and returns an [ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) if the link is valid, otherwise returns null. + +Signature: + +```typescript +export declare function parseActionCodeURL(link: string): ActionCodeURL | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| link | string | | + +Returns: + +[ActionCodeURL](./auth.actioncodeurl.md#actioncodeurl_class) \| null + +## deleteUser() + +Deletes and signs out the user. + +Important: this is a security-sensitive operation that requires the user to have recently signed in. If this requirement isn't met, ask the user to authenticate again and then call [reauthenticateWithCredential()](./auth.md#reauthenticatewithcredential). + +Signature: + +```typescript +export declare function deleteUser(user: User): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | + +Returns: + +Promise<void> + +## getIdToken() + +Returns a JSON Web Token (JWT) used to identify the user to a Firebase service. + +Returns the current token if it has not expired or if it will not expire in the next five minutes. Otherwise, this will refresh the token and return a new one. + +Signature: + +```typescript +export declare function getIdToken(user: User, forceRefresh?: boolean): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| forceRefresh | boolean | Force refresh regardless of token expiration. | + +Returns: + +Promise<string> + +## getIdTokenResult() + +Returns a deserialized JSON Web Token (JWT) used to identitfy the user to a Firebase service. + +Returns the current token if it has not expired or if it will not expire in the next five minutes. Otherwise, this will refresh the token and return a new one. + +Signature: + +```typescript +export declare function getIdTokenResult(user: User, forceRefresh?: boolean): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| forceRefresh | boolean | Force refresh regardless of token expiration. | + +Returns: + +Promise<[IdTokenResult](./auth.idtokenresult.md#idtokenresult_interface)> + +## linkWithCredential() + +Links the user account with the given credentials. + +An [AuthProvider](./auth.authprovider.md#authprovider_interface) can be used to generate the credential. + +Signature: + +```typescript +export declare function linkWithCredential(user: User, credential: AuthCredential): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| credential | [AuthCredential](./auth.authcredential.md#authcredential_class) | The auth credential. | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> + +## linkWithPhoneNumber() + +Links the user account with the given phone number. + +Signature: + +```typescript +export declare function linkWithPhoneNumber(user: User, phoneNumber: string, appVerifier: ApplicationVerifier): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| phoneNumber | string | The user's phone number in E.164 format (e.g. +16505550101). | +| appVerifier | [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) | The [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface). | + +Returns: + +Promise<[ConfirmationResult](./auth.confirmationresult.md#confirmationresult_interface)> + +## linkWithPopup() + +Links the authenticated provider to the user account using a pop-up based OAuth flow. + +If the linking is successful, the returned result will contain the user and the provider's credential. + +Signature: + +```typescript +export declare function linkWithPopup(user: User, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | +| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> + +### Example + + +```javascript +// Sign in using some other provider. +const result = await signInWithEmailAndPassword(auth, email, password); +// Link using a popup. +const provider = new FacebookAuthProvider(); +await linkWithPopup(result.user, provider); + +``` + +## linkWithRedirect() + +Links the [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) to the user account using a full-page redirect flow. + +To handle the results and errors for this operation, refer to [getRedirectResult()](./auth.md#getredirectresult). Follow the [best practices](https://firebase.google.com/docs/auth/web/redirect-best-practices) when using [linkWithRedirect()](./auth.md#linkwithredirect). + +Signature: + +```typescript +export declare function linkWithRedirect(user: User, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | +| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | + +Returns: + +Promise<never> + +### Example + + +```javascript +// Sign in using some other provider. +const result = await signInWithEmailAndPassword(auth, email, password); +// Link using a redirect. +const provider = new FacebookAuthProvider(); +await linkWithRedirect(result.user, provider); +// This will trigger a full page redirect away from your app + +// After returning from the redirect when your app initializes you can obtain the result +const result = await getRedirectResult(auth); + +``` + +## multiFactor() + +The [MultiFactorUser](./auth.multifactoruser.md#multifactoruser_interface) corresponding to the user. + +This is used to access all multi-factor properties and operations related to the user. + +Signature: + +```typescript +export declare function multiFactor(user: User): MultiFactorUser; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | + +Returns: + +[MultiFactorUser](./auth.multifactoruser.md#multifactoruser_interface) + +## reauthenticateWithCredential() + +Re-authenticates a user using a fresh credential. + +Use before operations such as [updatePassword()](./auth.md#updatepassword) that require tokens from recent sign-in attempts. This method can be used to recover from a `CREDENTIAL_TOO_OLD_LOGIN_AGAIN` error or a `TOKEN_EXPIRED` error. + +Signature: + +```typescript +export declare function reauthenticateWithCredential(user: User, credential: AuthCredential): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| credential | [AuthCredential](./auth.authcredential.md#authcredential_class) | The auth credential. | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> + +## reauthenticateWithPhoneNumber() + +Re-authenticates a user using a fresh phone credential. + +Use before operations such as [updatePassword()](./auth.md#updatepassword) that require tokens from recent sign-in attempts. + +Signature: + +```typescript +export declare function reauthenticateWithPhoneNumber(user: User, phoneNumber: string, appVerifier: ApplicationVerifier): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| phoneNumber | string | The user's phone number in E.164 format (e.g. +16505550101). | +| appVerifier | [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) | The [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface). | + +Returns: + +Promise<[ConfirmationResult](./auth.confirmationresult.md#confirmationresult_interface)> + +## reauthenticateWithPopup() + +Reauthenticates the current user with the specified [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) using a pop-up based OAuth flow. + +If the reauthentication is successful, the returned result will contain the user and the provider's credential. + +Signature: + +```typescript +export declare function reauthenticateWithPopup(user: User, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | +| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> + +### Example + + +```javascript +// Sign in using a popup. +const provider = new FacebookAuthProvider(); +const result = await signInWithPopup(auth, provider); +// Reauthenticate using a popup. +await reauthenticateWithPopup(result.user, provider); + +``` + +## reauthenticateWithRedirect() + +Reauthenticates the current user with the specified [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) using a full-page redirect flow. + +To handle the results and errors for this operation, refer to [getRedirectResult()](./auth.md#getredirectresult). Follow the [best practices](https://firebase.google.com/docs/auth/web/redirect-best-practices) when using [reauthenticateWithRedirect()](./auth.md#reauthenticatewithredirect). + +Signature: + +```typescript +export declare function reauthenticateWithRedirect(user: User, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| provider | [AuthProvider](./auth.authprovider.md#authprovider_interface) | The provider to authenticate. The provider has to be an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). Non-OAuth providers like [EmailAuthProvider](./auth.emailauthprovider.md#emailauthprovider_class) will throw an error. | +| resolver | [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) | An instance of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface), optional if already supplied to [initializeAuth()](./auth.md#initializeauth) or provided by [getAuth()](./auth.md#getauth). | + +Returns: + +Promise<never> + +### Example + + +```javascript +// Sign in using a redirect. +const provider = new FacebookAuthProvider(); +const result = await signInWithRedirect(auth, provider); +// This will trigger a full page redirect away from your app + +// After returning from the redirect when your app initializes you can obtain the result +const result = await getRedirectResult(auth); +// Reauthenticate using a redirect. +await reauthenticateWithRedirect(result.user, provider); +// This will again trigger a full page redirect away from your app + +// After returning from the redirect when your app initializes you can obtain the result +const result = await getRedirectResult(auth); + +``` + +## reload() + +Reloads user account data, if signed in. + +Signature: + +```typescript +export declare function reload(user: User): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | + +Returns: + +Promise<void> + +## sendEmailVerification() + +Sends a verification email to a user. + +The verification process is completed by calling [applyActionCode()](./auth.md#applyactioncode). + +Signature: + +```typescript +export declare function sendEmailVerification(user: User, actionCodeSettings?: ActionCodeSettings | null): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| actionCodeSettings | [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface) \| null | The [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface). | + +Returns: + +Promise<void> + +### Example + + +```javascript +const actionCodeSettings = { + url: 'https://www.example.com/?email=user@example.com', + iOS: { + bundleId: 'com.example.ios' + }, + android: { + packageName: 'com.example.android', + installApp: true, + minimumVersion: '12' + }, + handleCodeInApp: true +}; +await sendEmailVerification(user, actionCodeSettings); +// Obtain code from the user. +await applyActionCode(auth, code); + +``` + +## unlink() + +Unlinks a provider from a user account. + +Signature: + +```typescript +export declare function unlink(user: User, providerId: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| providerId | string | The provider to unlink. | + +Returns: + +Promise<[User](./auth.user.md#user_interface)> + +## updateEmail() + +Updates the user's email address. + +An email will be sent to the original email address (if it was set) that allows to revoke the email address change, in order to protect them from account hijacking. + +Important: this is a security sensitive operation that requires the user to have recently signed in. If this requirement isn't met, ask the user to authenticate again and then call [reauthenticateWithCredential()](./auth.md#reauthenticatewithcredential). + +Signature: + +```typescript +export declare function updateEmail(user: User, newEmail: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| newEmail | string | The new email address. | + +Returns: + +Promise<void> + +## updatePassword() + +Updates the user's password. + +Important: this is a security sensitive operation that requires the user to have recently signed in. If this requirement isn't met, ask the user to authenticate again and then call [reauthenticateWithCredential()](./auth.md#reauthenticatewithcredential). + +Signature: + +```typescript +export declare function updatePassword(user: User, newPassword: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| newPassword | string | The new password. | + +Returns: + +Promise<void> + +## updatePhoneNumber() + +Updates the user's phone number. + +Signature: + +```typescript +export declare function updatePhoneNumber(user: User, credential: PhoneAuthCredential): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| credential | [PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class) | A credential authenticating the new phone number. | + +Returns: + +Promise<void> + +### Example + + +``` +// 'recaptcha-container' is the ID of an element in the DOM. +const applicationVerifier = new RecaptchaVerifier('recaptcha-container'); +const provider = new PhoneAuthProvider(auth); +const verificationId = await provider.verifyPhoneNumber('+16505550101', applicationVerifier); +// Obtain the verificationCode from the user. +const phoneCredential = PhoneAuthProvider.credential(verificationId, verificationCode); +await updatePhoneNumber(user, phoneCredential); + +``` + +## updateProfile() + +Updates a user's profile data. + +Signature: + +```typescript +export declare function updateProfile(user: User, { displayName, photoURL: photoUrl }: { + displayName?: string | null; + photoURL?: string | null; +}): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| { displayName, photoURL: photoUrl } | { displayName?: string \| null; photoURL?: string \| null; } | | + +Returns: + +Promise<void> + +## verifyBeforeUpdateEmail() + +Sends a verification email to a new email address. + +The user's email will be updated to the new one after being verified. + +If you have a custom email action handler, you can complete the verification process by calling [applyActionCode()](./auth.md#applyactioncode). + +Signature: + +```typescript +export declare function verifyBeforeUpdateEmail(user: User, newEmail: string, actionCodeSettings?: ActionCodeSettings | null): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| user | [User](./auth.user.md#user_interface) | The user. | +| newEmail | string | The new email address to be verified before update. | +| actionCodeSettings | [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface) \| null | The [ActionCodeSettings](./auth.actioncodesettings.md#actioncodesettings_interface). | + +Returns: + +Promise<void> + +### Example + + +```javascript +const actionCodeSettings = { + url: 'https://www.example.com/?email=user@example.com', + iOS: { + bundleId: 'com.example.ios' + }, + android: { + packageName: 'com.example.android', + installApp: true, + minimumVersion: '12' + }, + handleCodeInApp: true +}; +await verifyBeforeUpdateEmail(user, 'newemail@example.com', actionCodeSettings); +// Obtain code from the user. +await applyActionCode(auth, code); + +``` + +## getAdditionalUserInfo() + +Extracts provider specific [AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface) for the given credential. + +Signature: + +```typescript +export declare function getAdditionalUserInfo(userCredential: UserCredential): AdditionalUserInfo | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | + +Returns: + +[AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface) \| null + +## ActionCodeOperation + +An enumeration of the possible email action types. + +Signature: + +```typescript +ActionCodeOperation: { + readonly EMAIL_SIGNIN: "EMAIL_SIGNIN"; + readonly PASSWORD_RESET: "PASSWORD_RESET"; + readonly RECOVER_EMAIL: "RECOVER_EMAIL"; + readonly REVERT_SECOND_FACTOR_ADDITION: "REVERT_SECOND_FACTOR_ADDITION"; + readonly VERIFY_AND_CHANGE_EMAIL: "VERIFY_AND_CHANGE_EMAIL"; + readonly VERIFY_EMAIL: "VERIFY_EMAIL"; +} +``` + +## AuthErrorCodes + +A map of potential `Auth` error codes, for easier comparison with errors thrown by the SDK. + +Note that you can't tree-shake individual keys in the map, so by using the map you might substantially increase your bundle size. + +Signature: + +```typescript +AUTH_ERROR_CODES_MAP_DO_NOT_USE_INTERNALLY: { + readonly ADMIN_ONLY_OPERATION: "auth/admin-restricted-operation"; + readonly ARGUMENT_ERROR: "auth/argument-error"; + readonly APP_NOT_AUTHORIZED: "auth/app-not-authorized"; + readonly APP_NOT_INSTALLED: "auth/app-not-installed"; + readonly CAPTCHA_CHECK_FAILED: "auth/captcha-check-failed"; + readonly CODE_EXPIRED: "auth/code-expired"; + readonly CORDOVA_NOT_READY: "auth/cordova-not-ready"; + readonly CORS_UNSUPPORTED: "auth/cors-unsupported"; + readonly CREDENTIAL_ALREADY_IN_USE: "auth/credential-already-in-use"; + readonly CREDENTIAL_MISMATCH: "auth/custom-token-mismatch"; + readonly CREDENTIAL_TOO_OLD_LOGIN_AGAIN: "auth/requires-recent-login"; + readonly DEPENDENT_SDK_INIT_BEFORE_AUTH: "auth/dependent-sdk-initialized-before-auth"; + readonly DYNAMIC_LINK_NOT_ACTIVATED: "auth/dynamic-link-not-activated"; + readonly EMAIL_CHANGE_NEEDS_VERIFICATION: "auth/email-change-needs-verification"; + readonly EMAIL_EXISTS: "auth/email-already-in-use"; + readonly EMULATOR_CONFIG_FAILED: "auth/emulator-config-failed"; + readonly EXPIRED_OOB_CODE: "auth/expired-action-code"; + readonly EXPIRED_POPUP_REQUEST: "auth/cancelled-popup-request"; + readonly INTERNAL_ERROR: "auth/internal-error"; + readonly INVALID_API_KEY: "auth/invalid-api-key"; + readonly INVALID_APP_CREDENTIAL: "auth/invalid-app-credential"; + readonly INVALID_APP_ID: "auth/invalid-app-id"; + readonly INVALID_AUTH: "auth/invalid-user-token"; + readonly INVALID_AUTH_EVENT: "auth/invalid-auth-event"; + readonly INVALID_CERT_HASH: "auth/invalid-cert-hash"; + readonly INVALID_CODE: "auth/invalid-verification-code"; + readonly INVALID_CONTINUE_URI: "auth/invalid-continue-uri"; + readonly INVALID_CORDOVA_CONFIGURATION: "auth/invalid-cordova-configuration"; + readonly INVALID_CUSTOM_TOKEN: "auth/invalid-custom-token"; + readonly INVALID_DYNAMIC_LINK_DOMAIN: "auth/invalid-dynamic-link-domain"; + readonly INVALID_EMAIL: "auth/invalid-email"; + readonly INVALID_EMULATOR_SCHEME: "auth/invalid-emulator-scheme"; + readonly INVALID_IDP_RESPONSE: "auth/invalid-credential"; + readonly INVALID_MESSAGE_PAYLOAD: "auth/invalid-message-payload"; + readonly INVALID_MFA_SESSION: "auth/invalid-multi-factor-session"; + readonly INVALID_OAUTH_CLIENT_ID: "auth/invalid-oauth-client-id"; + readonly INVALID_OAUTH_PROVIDER: "auth/invalid-oauth-provider"; + readonly INVALID_OOB_CODE: "auth/invalid-action-code"; + readonly INVALID_ORIGIN: "auth/unauthorized-domain"; + readonly INVALID_PASSWORD: "auth/wrong-password"; + readonly INVALID_PERSISTENCE: "auth/invalid-persistence-type"; + readonly INVALID_PHONE_NUMBER: "auth/invalid-phone-number"; + readonly INVALID_PROVIDER_ID: "auth/invalid-provider-id"; + readonly INVALID_RECIPIENT_EMAIL: "auth/invalid-recipient-email"; + readonly INVALID_SENDER: "auth/invalid-sender"; + readonly INVALID_SESSION_INFO: "auth/invalid-verification-id"; + readonly INVALID_TENANT_ID: "auth/invalid-tenant-id"; + readonly MFA_INFO_NOT_FOUND: "auth/multi-factor-info-not-found"; + readonly MFA_REQUIRED: "auth/multi-factor-auth-required"; + readonly MISSING_ANDROID_PACKAGE_NAME: "auth/missing-android-pkg-name"; + readonly MISSING_APP_CREDENTIAL: "auth/missing-app-credential"; + readonly MISSING_AUTH_DOMAIN: "auth/auth-domain-config-required"; + readonly MISSING_CODE: "auth/missing-verification-code"; + readonly MISSING_CONTINUE_URI: "auth/missing-continue-uri"; + readonly MISSING_IFRAME_START: "auth/missing-iframe-start"; + readonly MISSING_IOS_BUNDLE_ID: "auth/missing-ios-bundle-id"; + readonly MISSING_OR_INVALID_NONCE: "auth/missing-or-invalid-nonce"; + readonly MISSING_MFA_INFO: "auth/missing-multi-factor-info"; + readonly MISSING_MFA_SESSION: "auth/missing-multi-factor-session"; + readonly MISSING_PHONE_NUMBER: "auth/missing-phone-number"; + readonly MISSING_SESSION_INFO: "auth/missing-verification-id"; + readonly MODULE_DESTROYED: "auth/app-deleted"; + readonly NEED_CONFIRMATION: "auth/account-exists-with-different-credential"; + readonly NETWORK_REQUEST_FAILED: "auth/network-request-failed"; + readonly NULL_USER: "auth/null-user"; + readonly NO_AUTH_EVENT: "auth/no-auth-event"; + readonly NO_SUCH_PROVIDER: "auth/no-such-provider"; + readonly OPERATION_NOT_ALLOWED: "auth/operation-not-allowed"; + readonly OPERATION_NOT_SUPPORTED: "auth/operation-not-supported-in-this-environment"; + readonly POPUP_BLOCKED: "auth/popup-blocked"; + readonly POPUP_CLOSED_BY_USER: "auth/popup-closed-by-user"; + readonly PROVIDER_ALREADY_LINKED: "auth/provider-already-linked"; + readonly QUOTA_EXCEEDED: "auth/quota-exceeded"; + readonly REDIRECT_CANCELLED_BY_USER: "auth/redirect-cancelled-by-user"; + readonly REDIRECT_OPERATION_PENDING: "auth/redirect-operation-pending"; + readonly REJECTED_CREDENTIAL: "auth/rejected-credential"; + readonly SECOND_FACTOR_ALREADY_ENROLLED: "auth/second-factor-already-in-use"; + readonly SECOND_FACTOR_LIMIT_EXCEEDED: "auth/maximum-second-factor-count-exceeded"; + readonly TENANT_ID_MISMATCH: "auth/tenant-id-mismatch"; + readonly TIMEOUT: "auth/timeout"; + readonly TOKEN_EXPIRED: "auth/user-token-expired"; + readonly TOO_MANY_ATTEMPTS_TRY_LATER: "auth/too-many-requests"; + readonly UNAUTHORIZED_DOMAIN: "auth/unauthorized-continue-uri"; + readonly UNSUPPORTED_FIRST_FACTOR: "auth/unsupported-first-factor"; + readonly UNSUPPORTED_PERSISTENCE: "auth/unsupported-persistence-type"; + readonly UNSUPPORTED_TENANT_OPERATION: "auth/unsupported-tenant-operation"; + readonly UNVERIFIED_EMAIL: "auth/unverified-email"; + readonly USER_CANCELLED: "auth/user-cancelled"; + readonly USER_DELETED: "auth/user-not-found"; + readonly USER_DISABLED: "auth/user-disabled"; + readonly USER_MISMATCH: "auth/user-mismatch"; + readonly USER_SIGNED_OUT: "auth/user-signed-out"; + readonly WEAK_PASSWORD: "auth/weak-password"; + readonly WEB_STORAGE_UNSUPPORTED: "auth/web-storage-unsupported"; + readonly ALREADY_INITIALIZED: "auth/already-initialized"; +} +``` + +## browserLocalPersistence + +An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type `LOCAL` using `localStorage` for the underlying storage. + +Signature: + +```typescript +browserLocalPersistence: Persistence +``` + +## browserPopupRedirectResolver + +An implementation of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) suitable for browser based applications. + +Signature: + +```typescript +browserPopupRedirectResolver: PopupRedirectResolver +``` + +## browserSessionPersistence + +An implementation of [Persistence](./auth.persistence.md#persistence_interface) of `SESSION` using `sessionStorage` for the underlying storage. + +Signature: + +```typescript +browserSessionPersistence: Persistence +``` + +## cordovaPopupRedirectResolver + +An implementation of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) suitable for Cordova based applications. + +Signature: + +```typescript +cordovaPopupRedirectResolver: PopupRedirectResolver +``` + +## debugErrorMap + +A verbose error map with detailed descriptions for most error codes. + +See discussion at [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) + +Signature: + +```typescript +debugErrorMap: AuthErrorMap +``` + +## FactorId + +An enum of factors that may be used for multifactor authentication. + +Signature: + +```typescript +FactorId: { + readonly PHONE: "phone"; +} +``` + +## indexedDBLocalPersistence + +An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type `LOCAL` using `indexedDB` for the underlying storage. + +Signature: + +```typescript +indexedDBLocalPersistence: Persistence +``` + +## inMemoryPersistence + +An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type 'NONE'. + +Signature: + +```typescript +inMemoryPersistence: Persistence +``` + +## OperationType + +Enumeration of supported operation types. + +Signature: + +```typescript +OperationType: { + readonly LINK: "link"; + readonly REAUTHENTICATE: "reauthenticate"; + readonly SIGN_IN: "signIn"; +} +``` + +## prodErrorMap + +A minimal error map with all verbose error messages stripped. + +See discussion at [AuthErrorMap](./auth.autherrormap.md#autherrormap_interface) + +Signature: + +```typescript +prodErrorMap: AuthErrorMap +``` + +## ProviderId + +Enumeration of supported providers. + +Signature: + +```typescript +ProviderId: { + readonly FACEBOOK: "facebook.com"; + readonly GITHUB: "github.com"; + readonly GOOGLE: "google.com"; + readonly PASSWORD: "password"; + readonly PHONE: "phone"; + readonly TWITTER: "twitter.com"; +} +``` + +## reactNativeLocalPersistence + +An implementation of [Persistence](./auth.persistence.md#persistence_interface) of type 'LOCAL' for use in React Native environments. + +Signature: + +```typescript +reactNativeLocalPersistence: Persistence +``` + +## SignInMethod + +Enumeration of supported sign-in methods. + +Signature: + +```typescript +SignInMethod: { + readonly EMAIL_LINK: "emailLink"; + readonly EMAIL_PASSWORD: "password"; + readonly FACEBOOK: "facebook.com"; + readonly GITHUB: "github.com"; + readonly GOOGLE: "google.com"; + readonly PHONE: "phone"; + readonly TWITTER: "twitter.com"; +} +``` + +## CustomParameters + +Map of OAuth Custom Parameters. + +Signature: + +```typescript +export declare type CustomParameters = Record; +``` + +## NextOrObserver + +Type definition for an event callback. + +Signature: + +```typescript +export declare type NextOrObserver = NextFn | Observer; +``` + +## PhoneInfoOptions + +The information required to verify the ownership of a phone number. + +The information that's required depends on whether you are doing single-factor sign-in, multi-factor enrollment or multi-factor sign-in. + +Signature: + +```typescript +export declare type PhoneInfoOptions = PhoneSingleFactorInfoOptions | PhoneMultiFactorEnrollInfoOptions | PhoneMultiFactorSignInInfoOptions; +``` + +## UserProfile + +User profile used in [AdditionalUserInfo](./auth.additionaluserinfo.md#additionaluserinfo_interface). + +Signature: + +```typescript +export declare type UserProfile = Record; +``` diff --git a/docs-devsite/auth.multifactorassertion.md b/docs-devsite/auth.multifactorassertion.md new file mode 100644 index 00000000000..d7937ec1f64 --- /dev/null +++ b/docs-devsite/auth.multifactorassertion.md @@ -0,0 +1,37 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# MultiFactorAssertion interface +The base class for asserting ownership of a second factor. + +This is used to facilitate enrollment of a second factor on an existing user or sign-in of a user who already verified the first factor. + +Signature: + +```typescript +export interface MultiFactorAssertion +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [factorId](./auth.multifactorassertion.md#multifactorassertionfactorid) | typeof [FactorIdMap](./auth.md#factorid)\[keyof typeof [FactorIdMap](./auth.md#factorid)\] | The identifier of the second factor. | + +## MultiFactorAssertion.factorId + +The identifier of the second factor. + +Signature: + +```typescript +readonly factorId: typeof FactorIdMap[keyof typeof FactorIdMap]; +``` diff --git a/docs-devsite/auth.multifactorerror.md b/docs-devsite/auth.multifactorerror.md new file mode 100644 index 00000000000..a13276f5a61 --- /dev/null +++ b/docs-devsite/auth.multifactorerror.md @@ -0,0 +1,67 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# MultiFactorError interface +The error thrown when the user needs to provide a second factor to sign in successfully. + +The error code for this error is `auth/multi-factor-auth-required`. + +Signature: + +```typescript +export interface MultiFactorError extends AuthError +``` +Extends: [AuthError](./auth.autherror.md#autherror_interface) + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [customData](./auth.multifactorerror.md#multifactorerrorcustomdata) | [AuthError](./auth.autherror.md#autherror_interface)\['customData'\] & { readonly operationType: typeof [OperationTypeMap](./auth.md#operationtype)\[keyof typeof [OperationTypeMap](./auth.md#operationtype)\]; } | Details about the MultiFactorError. | + +## MultiFactorError.customData + +Details about the MultiFactorError. + +Signature: + +```typescript +readonly customData: AuthError['customData'] & { + readonly operationType: typeof OperationTypeMap[keyof typeof OperationTypeMap]; + }; +``` + +### Example + + +```javascript +let resolver; +let multiFactorHints; + +signInWithEmailAndPassword(auth, email, password) + .then((result) => { + // User signed in. No 2nd factor challenge is needed. + }) + .catch((error) => { + if (error.code == 'auth/multi-factor-auth-required') { + resolver = getMultiFactorResolver(auth, error); + multiFactorHints = resolver.hints; + } else { + // Handle other errors. + } + }); + +// Obtain a multiFactorAssertion by verifying the second factor. + +const userCredential = await resolver.resolveSignIn(multiFactorAssertion); + +``` + diff --git a/docs-devsite/auth.multifactorinfo.md b/docs-devsite/auth.multifactorinfo.md new file mode 100644 index 00000000000..80a56164b9a --- /dev/null +++ b/docs-devsite/auth.multifactorinfo.md @@ -0,0 +1,68 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# MultiFactorInfo interface +A structure containing the information of a second factor entity. + +Signature: + +```typescript +export interface MultiFactorInfo +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [displayName](./auth.multifactorinfo.md#multifactorinfodisplayname) | string \| null | The user friendly name of the current second factor. | +| [enrollmentTime](./auth.multifactorinfo.md#multifactorinfoenrollmenttime) | string | The enrollment date of the second factor formatted as a UTC string. | +| [factorId](./auth.multifactorinfo.md#multifactorinfofactorid) | typeof [FactorIdMap](./auth.md#factorid)\[keyof typeof [FactorIdMap](./auth.md#factorid)\] | The identifier of the second factor. | +| [uid](./auth.multifactorinfo.md#multifactorinfouid) | string | The multi-factor enrollment ID. | + +## MultiFactorInfo.displayName + +The user friendly name of the current second factor. + +Signature: + +```typescript +readonly displayName?: string | null; +``` + +## MultiFactorInfo.enrollmentTime + +The enrollment date of the second factor formatted as a UTC string. + +Signature: + +```typescript +readonly enrollmentTime: string; +``` + +## MultiFactorInfo.factorId + +The identifier of the second factor. + +Signature: + +```typescript +readonly factorId: typeof FactorIdMap[keyof typeof FactorIdMap]; +``` + +## MultiFactorInfo.uid + +The multi-factor enrollment ID. + +Signature: + +```typescript +readonly uid: string; +``` diff --git a/docs-devsite/auth.multifactorresolver.md b/docs-devsite/auth.multifactorresolver.md new file mode 100644 index 00000000000..9d6bc3ebcda --- /dev/null +++ b/docs-devsite/auth.multifactorresolver.md @@ -0,0 +1,128 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# MultiFactorResolver interface +The class used to facilitate recovery from [MultiFactorError](./auth.multifactorerror.md#multifactorerror_interface) when a user needs to provide a second factor to sign in. + +Signature: + +```typescript +export interface MultiFactorResolver +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [hints](./auth.multifactorresolver.md#multifactorresolverhints) | [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface)\[\] | The list of hints for the second factors needed to complete the sign-in for the current session. | +| [session](./auth.multifactorresolver.md#multifactorresolversession) | [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) | The session identifier for the current sign-in flow, which can be used to complete the second factor sign-in. | + +## Methods + +| Method | Description | +| --- | --- | +| [resolveSignIn(assertion)](./auth.multifactorresolver.md#multifactorresolverresolvesignin) | A helper function to help users complete sign in with a second factor using an [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) confirming the user successfully completed the second factor challenge. | + +## MultiFactorResolver.hints + +The list of hints for the second factors needed to complete the sign-in for the current session. + +Signature: + +```typescript +readonly hints: MultiFactorInfo[]; +``` + +## MultiFactorResolver.session + +The session identifier for the current sign-in flow, which can be used to complete the second factor sign-in. + +Signature: + +```typescript +readonly session: MultiFactorSession; +``` + +## MultiFactorResolver.resolveSignIn() + +A helper function to help users complete sign in with a second factor using an [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) confirming the user successfully completed the second factor challenge. + +Signature: + +```typescript +resolveSignIn(assertion: MultiFactorAssertion): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| assertion | [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) | The multi-factor assertion to resolve sign-in with. | + +Returns: + +Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)> + +The promise that resolves with the user credential object. + +### Example + + +```javascript +const phoneAuthCredential = PhoneAuthProvider.credential(verificationId, verificationCode); +const multiFactorAssertion = PhoneMultiFactorGenerator.assertion(phoneAuthCredential); +const userCredential = await resolver.resolveSignIn(multiFactorAssertion); + +``` + +### Example + + +```javascript +let resolver; +let multiFactorHints; + +signInWithEmailAndPassword(auth, email, password) + .then((result) => { + // User signed in. No 2nd factor challenge is needed. + }) + .catch((error) => { + if (error.code == 'auth/multi-factor-auth-required') { + resolver = getMultiFactorResolver(auth, error); + // Show UI to let user select second factor. + multiFactorHints = resolver.hints; + } else { + // Handle other errors. + } + }); + +// The enrolled second factors that can be used to complete +// sign-in are returned in the `MultiFactorResolver.hints` list. +// UI needs to be presented to allow the user to select a second factor +// from that list. + +const selectedHint = // ; selected from multiFactorHints +const phoneAuthProvider = new PhoneAuthProvider(auth); +const phoneInfoOptions = { + multiFactorHint: selectedHint, + session: resolver.session +}; +const verificationId = phoneAuthProvider.verifyPhoneNumber(phoneInfoOptions, appVerifier); +// Store `verificationId` and show UI to let user enter verification code. + +// UI to enter verification code and continue. +// Continue button click handler +const phoneAuthCredential = PhoneAuthProvider.credential(verificationId, verificationCode); +const multiFactorAssertion = PhoneMultiFactorGenerator.assertion(phoneAuthCredential); +const userCredential = await resolver.resolveSignIn(multiFactorAssertion); + +``` + diff --git a/docs-devsite/auth.multifactorsession.md b/docs-devsite/auth.multifactorsession.md new file mode 100644 index 00000000000..9ad2d0a1682 --- /dev/null +++ b/docs-devsite/auth.multifactorsession.md @@ -0,0 +1,19 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# MultiFactorSession interface +An interface defining the multi-factor session object used for enrolling a second factor on a user or helping sign in an enrolled user with a second factor. + +Signature: + +```typescript +export interface MultiFactorSession +``` diff --git a/docs-devsite/auth.multifactoruser.md b/docs-devsite/auth.multifactoruser.md new file mode 100644 index 00000000000..9f25e4174fc --- /dev/null +++ b/docs-devsite/auth.multifactoruser.md @@ -0,0 +1,161 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# MultiFactorUser interface +An interface that defines the multi-factor related properties and operations pertaining to a [User](./auth.user.md#user_interface). + +Signature: + +```typescript +export interface MultiFactorUser +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [enrolledFactors](./auth.multifactoruser.md#multifactoruserenrolledfactors) | [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface)\[\] | Returns a list of the user's enrolled second factors. | + +## Methods + +| Method | Description | +| --- | --- | +| [enroll(assertion, displayName)](./auth.multifactoruser.md#multifactoruserenroll) | Enrolls a second factor as identified by the [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) for the user. | +| [getSession()](./auth.multifactoruser.md#multifactorusergetsession) | Returns the session identifier for a second factor enrollment operation. This is used to identify the user trying to enroll a second factor. | +| [unenroll(option)](./auth.multifactoruser.md#multifactoruserunenroll) | Unenrolls the specified second factor. | + +## MultiFactorUser.enrolledFactors + +Returns a list of the user's enrolled second factors. + +Signature: + +```typescript +readonly enrolledFactors: MultiFactorInfo[]; +``` + +## MultiFactorUser.enroll() + +Enrolls a second factor as identified by the [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) for the user. + +On resolution, the user tokens are updated to reflect the change in the JWT payload. Accepts an additional display name parameter used to identify the second factor to the end user. Recent re-authentication is required for this operation to succeed. On successful enrollment, existing Firebase sessions (refresh tokens) are revoked. When a new factor is enrolled, an email notification is sent to the user’s email. + +Signature: + +```typescript +enroll(assertion: MultiFactorAssertion, displayName?: string | null): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| assertion | [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) | The multi-factor assertion to enroll with. | +| displayName | string \| null | The display name of the second factor. | + +Returns: + +Promise<void> + +### Example + + +```javascript +const multiFactorUser = multiFactor(auth.currentUser); +const multiFactorSession = await multiFactorUser.getSession(); + +// Send verification code. +const phoneAuthProvider = new PhoneAuthProvider(auth); +const phoneInfoOptions = { + phoneNumber: phoneNumber, + session: multiFactorSession +}; +const verificationId = await phoneAuthProvider.verifyPhoneNumber(phoneInfoOptions, appVerifier); + +// Obtain verification code from user. +const phoneAuthCredential = PhoneAuthProvider.credential(verificationId, verificationCode); +const multiFactorAssertion = PhoneMultiFactorGenerator.assertion(phoneAuthCredential); +await multiFactorUser.enroll(multiFactorAssertion); +// Second factor enrolled. + +``` + +## MultiFactorUser.getSession() + +Returns the session identifier for a second factor enrollment operation. This is used to identify the user trying to enroll a second factor. + +Signature: + +```typescript +getSession(): Promise; +``` +Returns: + +Promise<[MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface)> + +The promise that resolves with the [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface). + +### Example + + +```javascript +const multiFactorUser = multiFactor(auth.currentUser); +const multiFactorSession = await multiFactorUser.getSession(); + +// Send verification code. +const phoneAuthProvider = new PhoneAuthProvider(auth); +const phoneInfoOptions = { + phoneNumber: phoneNumber, + session: multiFactorSession +}; +const verificationId = await phoneAuthProvider.verifyPhoneNumber(phoneInfoOptions, appVerifier); + +// Obtain verification code from user. +const phoneAuthCredential = PhoneAuthProvider.credential(verificationId, verificationCode); +const multiFactorAssertion = PhoneMultiFactorGenerator.assertion(phoneAuthCredential); +await multiFactorUser.enroll(multiFactorAssertion); + +``` + +## MultiFactorUser.unenroll() + +Unenrolls the specified second factor. + +To specify the factor to remove, pass a [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) object (retrieved from [MultiFactorUser.enrolledFactors](./auth.multifactoruser.md#multifactoruserenrolledfactors)) or the factor's UID string. Sessions are not revoked when the account is unenrolled. An email notification is likely to be sent to the user notifying them of the change. Recent re-authentication is required for this operation to succeed. When an existing factor is unenrolled, an email notification is sent to the user’s email. + +Signature: + +```typescript +unenroll(option: MultiFactorInfo | string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| option | [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) \| string | The multi-factor option to unenroll. | + +Returns: + +Promise<void> + +- A `Promise` which resolves when the unenroll operation is complete. + +### Example + + +```javascript +const multiFactorUser = multiFactor(auth.currentUser); +// Present user the option to choose which factor to unenroll. +await multiFactorUser.unenroll(multiFactorUser.enrolledFactors[i]) + +``` + diff --git a/docs-devsite/auth.oauthcredential.md b/docs-devsite/auth.oauthcredential.md new file mode 100644 index 00000000000..dc3855e01a1 --- /dev/null +++ b/docs-devsite/auth.oauthcredential.md @@ -0,0 +1,105 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# OAuthCredential class +Represents the OAuth credentials returned by an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class). + +Implementations specify the details about each auth provider's credential requirements. + +Signature: + +```typescript +export declare class OAuthCredential extends AuthCredential +``` +Extends: [AuthCredential](./auth.authcredential.md#authcredential_class) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [accessToken](./auth.oauthcredential.md#oauthcredentialaccesstoken) | | string | The OAuth access token associated with the credential if it belongs to an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class), such as facebook.com, twitter.com, etc. | +| [idToken](./auth.oauthcredential.md#oauthcredentialidtoken) | | string | The OAuth ID token associated with the credential if it belongs to an OIDC provider, such as google.com. | +| [secret](./auth.oauthcredential.md#oauthcredentialsecret) | | string | The OAuth access token secret associated with the credential if it belongs to an OAuth 1.0 provider, such as twitter.com. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [fromJSON(json)](./auth.oauthcredential.md#oauthcredentialfromjson) | static | Static method to deserialize a JSON representation of an object into an [AuthCredential](./auth.authcredential.md#authcredential_class). | +| [toJSON()](./auth.oauthcredential.md#oauthcredentialtojson) | | Returns a JSON-serializable representation of this object. | + +## OAuthCredential.accessToken + +The OAuth access token associated with the credential if it belongs to an [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class), such as `facebook.com`, `twitter.com`, etc. + +Signature: + +```typescript +accessToken?: string; +``` + +## OAuthCredential.idToken + +The OAuth ID token associated with the credential if it belongs to an OIDC provider, such as `google.com`. + +Signature: + +```typescript +idToken?: string; +``` + +## OAuthCredential.secret + +The OAuth access token secret associated with the credential if it belongs to an OAuth 1.0 provider, such as `twitter.com`. + +Signature: + +```typescript +secret?: string; +``` + +## OAuthCredential.fromJSON() + +Static method to deserialize a JSON representation of an object into an [AuthCredential](./auth.authcredential.md#authcredential_class). + +Signature: + +```typescript +static fromJSON(json: string | object): OAuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| json | string \| object | Input can be either Object or the stringified representation of the object. When string is provided, JSON.parse would be called first. | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null + +If the JSON input does not represent an [AuthCredential](./auth.authcredential.md#authcredential_class), null is returned. + +## OAuthCredential.toJSON() + +Returns a JSON-serializable representation of this object. + +Signature: + +```typescript +toJSON(): object; +``` +Returns: + +object + +a JSON-serializable representation of this object. + diff --git a/docs-devsite/auth.oauthcredentialoptions.md b/docs-devsite/auth.oauthcredentialoptions.md new file mode 100644 index 00000000000..0389c534c17 --- /dev/null +++ b/docs-devsite/auth.oauthcredentialoptions.md @@ -0,0 +1,61 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# OAuthCredentialOptions interface +Defines the options for initializing an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). + +For ID tokens with nonce claim, the raw nonce has to also be provided. + +Signature: + +```typescript +export interface OAuthCredentialOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [accessToken](./auth.oauthcredentialoptions.md#oauthcredentialoptionsaccesstoken) | string | The OAuth access token used to initialize the [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). | +| [idToken](./auth.oauthcredentialoptions.md#oauthcredentialoptionsidtoken) | string | The OAuth ID token used to initialize the [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). | +| [rawNonce](./auth.oauthcredentialoptions.md#oauthcredentialoptionsrawnonce) | string | The raw nonce associated with the ID token. | + +## OAuthCredentialOptions.accessToken + +The OAuth access token used to initialize the [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). + +Signature: + +```typescript +accessToken?: string; +``` + +## OAuthCredentialOptions.idToken + +The OAuth ID token used to initialize the [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). + +Signature: + +```typescript +idToken?: string; +``` + +## OAuthCredentialOptions.rawNonce + +The raw nonce associated with the ID token. + +It is required when an ID token with a nonce field is provided. The SHA-256 hash of the raw nonce must match the nonce field in the ID token. + +Signature: + +```typescript +rawNonce?: string; +``` diff --git a/docs-devsite/auth.oauthprovider.md b/docs-devsite/auth.oauthprovider.md new file mode 100644 index 00000000000..30141fcce40 --- /dev/null +++ b/docs-devsite/auth.oauthprovider.md @@ -0,0 +1,168 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# OAuthProvider class +Provider for generating generic [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class). + +Signature: + +```typescript +export declare class OAuthProvider extends BaseOAuthProvider +``` +Extends: BaseOAuthProvider + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [credential(params)](./auth.oauthprovider.md#oauthprovidercredential) | | Creates a [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a generic OAuth provider's access token or ID token. | +| [credentialFromError(error)](./auth.oauthprovider.md#oauthprovidercredentialfromerror) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. | +| [credentialFromJSON(json)](./auth.oauthprovider.md#oauthprovidercredentialfromjson) | static | Creates an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a JSON string or a plain object. | +| [credentialFromResult(userCredential)](./auth.oauthprovider.md#oauthprovidercredentialfromresult) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). | + +## OAuthProvider.credential() + +Creates a [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a generic OAuth provider's access token or ID token. + +The raw nonce is required when an ID token with a nonce field is provided. The SHA-256 hash of the raw nonce must match the nonce field in the ID token. + +Signature: + +```typescript +credential(params: OAuthCredentialOptions): OAuthCredential; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| params | [OAuthCredentialOptions](./auth.oauthcredentialoptions.md#oauthcredentialoptions_interface) | Either the options object containing the ID token, access token and raw nonce or the ID token string. | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) + +### Example + + +```javascript +// `googleUser` from the onsuccess Google Sign In callback. +// Initialize a generate OAuth provider with a `google.com` providerId. +const provider = new OAuthProvider('google.com'); +const credential = provider.credential({ + idToken: googleUser.getAuthResponse().id_token, +}); +const result = await signInWithCredential(credential); + +``` + +## OAuthProvider.credentialFromError() + +Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. + +Signature: + +```typescript +static credentialFromError(error: FirebaseError): OAuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null + +## OAuthProvider.credentialFromJSON() + +Creates an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a JSON string or a plain object. + +Signature: + +```typescript +static credentialFromJSON(json: object | string): OAuthCredential; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| json | object \| string | A plain object or a JSON string | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) + +## OAuthProvider.credentialFromResult() + +Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). + +Signature: + +```typescript +static credentialFromResult(userCredential: UserCredential): OAuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null + +### Example 1 + + +```javascript +// Sign in using a redirect. +const provider = new OAuthProvider('google.com'); +// Start a sign in process for an unauthenticated user. +provider.addScope('profile'); +provider.addScope('email'); +await signInWithRedirect(auth, provider); +// This will trigger a full page redirect away from your app + +// After returning from the redirect when your app initializes you can obtain the result +const result = await getRedirectResult(auth); +if (result) { + // This is the signed-in user + const user = result.user; + // This gives you a OAuth Access Token for the provider. + const credential = provider.credentialFromResult(auth, result); + const token = credential.accessToken; +} + +``` + +### Example 2 + + +```javascript +// Sign in using a popup. +const provider = new OAuthProvider('google.com'); +provider.addScope('profile'); +provider.addScope('email'); +const result = await signInWithPopup(auth, provider); + +// The signed-in user info. +const user = result.user; +// This gives you a OAuth Access Token for the provider. +const credential = provider.credentialFromResult(auth, result); +const token = credential.accessToken; + +``` + diff --git a/docs-devsite/auth.parsedtoken.md b/docs-devsite/auth.parsedtoken.md new file mode 100644 index 00000000000..7892b135536 --- /dev/null +++ b/docs-devsite/auth.parsedtoken.md @@ -0,0 +1,83 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ParsedToken interface +Interface representing a parsed ID token. + +Signature: + +```typescript +export interface ParsedToken +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [auth\_time](./auth.parsedtoken.md#parsedtokenauth_time) | string | Time at which authentication was performed. | +| [exp](./auth.parsedtoken.md#parsedtokenexp) | string | Expiration time of the token. | +| [firebase](./auth.parsedtoken.md#parsedtokenfirebase) | { 'sign\_in\_provider'?: string; 'sign\_in\_second\_factor'?: string; 'identities'?: Record<string, string>; } | Firebase specific claims, containing the provider(s) used to authenticate the user. | +| [iat](./auth.parsedtoken.md#parsedtokeniat) | string | Issuance time of the token. | +| [sub](./auth.parsedtoken.md#parsedtokensub) | string | UID of the user. | + +## ParsedToken.auth\_time + +Time at which authentication was performed. + +Signature: + +```typescript +'auth_time'?: string; +``` + +## ParsedToken.exp + +Expiration time of the token. + +Signature: + +```typescript +'exp'?: string; +``` + +## ParsedToken.firebase + +Firebase specific claims, containing the provider(s) used to authenticate the user. + +Signature: + +```typescript +'firebase'?: { + 'sign_in_provider'?: string; + 'sign_in_second_factor'?: string; + 'identities'?: Record; + }; +``` + +## ParsedToken.iat + +Issuance time of the token. + +Signature: + +```typescript +'iat'?: string; +``` + +## ParsedToken.sub + +UID of the user. + +Signature: + +```typescript +'sub'?: string; +``` diff --git a/docs-devsite/auth.persistence.md b/docs-devsite/auth.persistence.md new file mode 100644 index 00000000000..b3f9ecb11e1 --- /dev/null +++ b/docs-devsite/auth.persistence.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Persistence interface +An interface covering the possible persistence mechanism types. + +Signature: + +```typescript +export interface Persistence +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [type](./auth.persistence.md#persistencetype) | 'SESSION' \| 'LOCAL' \| 'NONE' | Type of Persistence. - 'SESSION' is used for temporary persistence such as sessionStorage. - 'LOCAL' is used for long term persistence such as localStorage or IndexedDB. - 'NONE' is used for in-memory, or no persistence. | + +## Persistence.type + +Type of Persistence. - 'SESSION' is used for temporary persistence such as `sessionStorage`. - 'LOCAL' is used for long term persistence such as `localStorage` or `IndexedDB`. - 'NONE' is used for in-memory, or no persistence. + +Signature: + +```typescript +readonly type: 'SESSION' | 'LOCAL' | 'NONE'; +``` diff --git a/docs-devsite/auth.phoneauthcredential.md b/docs-devsite/auth.phoneauthcredential.md new file mode 100644 index 00000000000..44a85db5254 --- /dev/null +++ b/docs-devsite/auth.phoneauthcredential.md @@ -0,0 +1,63 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# PhoneAuthCredential class +Represents the credentials returned by [PhoneAuthProvider](./auth.phoneauthprovider.md#phoneauthprovider_class). + +Signature: + +```typescript +export declare class PhoneAuthCredential extends AuthCredential +``` +Extends: [AuthCredential](./auth.authcredential.md#authcredential_class) + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [fromJSON(json)](./auth.phoneauthcredential.md#phoneauthcredentialfromjson) | static | Generates a phone credential based on a plain object or a JSON string. | +| [toJSON()](./auth.phoneauthcredential.md#phoneauthcredentialtojson) | | Returns a JSON-serializable representation of this object. | + +## PhoneAuthCredential.fromJSON() + +Generates a phone credential based on a plain object or a JSON string. + +Signature: + +```typescript +static fromJSON(json: object | string): PhoneAuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| json | object \| string | | + +Returns: + +[PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class) \| null + +## PhoneAuthCredential.toJSON() + +Returns a JSON-serializable representation of this object. + +Signature: + +```typescript +toJSON(): object; +``` +Returns: + +object + +a JSON-serializable representation of this object. + diff --git a/docs-devsite/auth.phoneauthprovider.md b/docs-devsite/auth.phoneauthprovider.md new file mode 100644 index 00000000000..41e743386de --- /dev/null +++ b/docs-devsite/auth.phoneauthprovider.md @@ -0,0 +1,256 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# PhoneAuthProvider class +Provider for generating an [PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class). + +Signature: + +```typescript +export declare class PhoneAuthProvider +``` + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(auth)](./auth.phoneauthprovider.md#phoneauthproviderconstructor) | | Constructs a new instance of the PhoneAuthProvider class | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [PHONE\_SIGN\_IN\_METHOD](./auth.phoneauthprovider.md#phoneauthproviderphone_sign_in_method) | static | 'phone' | Always set to [SignInMethod](./auth.md#signinmethod).PHONE. | +| [PROVIDER\_ID](./auth.phoneauthprovider.md#phoneauthproviderprovider_id) | static | 'phone' | Always set to [ProviderId](./auth.md#providerid).PHONE. | +| [providerId](./auth.phoneauthprovider.md#phoneauthproviderproviderid) | | "phone" | Always set to [ProviderId](./auth.md#providerid).PHONE. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [credential(verificationId, verificationCode)](./auth.phoneauthprovider.md#phoneauthprovidercredential) | static | Creates a phone auth credential, given the verification ID from [PhoneAuthProvider.verifyPhoneNumber()](./auth.phoneauthprovider.md#phoneauthproviderverifyphonenumber) and the code that was sent to the user's mobile device. | +| [credentialFromError(error)](./auth.phoneauthprovider.md#phoneauthprovidercredentialfromerror) | static | Returns an [AuthCredential](./auth.authcredential.md#authcredential_class) when passed an error. | +| [credentialFromResult(userCredential)](./auth.phoneauthprovider.md#phoneauthprovidercredentialfromresult) | static | Generates an [AuthCredential](./auth.authcredential.md#authcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). | +| [verifyPhoneNumber(phoneOptions, applicationVerifier)](./auth.phoneauthprovider.md#phoneauthproviderverifyphonenumber) | | Starts a phone number authentication flow by sending a verification code to the given phone number. | + +## PhoneAuthProvider.(constructor) + +Constructs a new instance of the `PhoneAuthProvider` class + +Signature: + +```typescript +constructor(auth: Auth); +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| auth | [Auth](./auth.auth.md#auth_interface) | The Firebase [Auth](./auth.auth.md#auth_interface) instance in which sign-ins should occur. | + +## PhoneAuthProvider.PHONE\_SIGN\_IN\_METHOD + +Always set to [SignInMethod](./auth.md#signinmethod).PHONE. + +Signature: + +```typescript +static readonly PHONE_SIGN_IN_METHOD: 'phone'; +``` + +## PhoneAuthProvider.PROVIDER\_ID + +Always set to [ProviderId](./auth.md#providerid).PHONE. + +Signature: + +```typescript +static readonly PROVIDER_ID: 'phone'; +``` + +## PhoneAuthProvider.providerId + +Always set to [ProviderId](./auth.md#providerid).PHONE. + +Signature: + +```typescript +readonly providerId: "phone"; +``` + +## PhoneAuthProvider.credential() + +Creates a phone auth credential, given the verification ID from [PhoneAuthProvider.verifyPhoneNumber()](./auth.phoneauthprovider.md#phoneauthproviderverifyphonenumber) and the code that was sent to the user's mobile device. + +Signature: + +```typescript +static credential(verificationId: string, verificationCode: string): PhoneAuthCredential; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| verificationId | string | The verification ID returned from [PhoneAuthProvider.verifyPhoneNumber()](./auth.phoneauthprovider.md#phoneauthproviderverifyphonenumber). | +| verificationCode | string | The verification code sent to the user's mobile device. | + +Returns: + +[PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class) + +The auth provider credential. + +### Example 1 + + +```javascript +const provider = new PhoneAuthProvider(auth); +const verificationId = provider.verifyPhoneNumber(phoneNumber, applicationVerifier); +// Obtain verificationCode from the user. +const authCredential = PhoneAuthProvider.credential(verificationId, verificationCode); +const userCredential = signInWithCredential(auth, authCredential); + +``` + +### Example 2 + +An alternative flow is provided using the `signInWithPhoneNumber` method. + +```javascript +const confirmationResult = await signInWithPhoneNumber(auth, phoneNumber, applicationVerifier); +// Obtain verificationCode from the user. +const userCredential = await confirmationResult.confirm(verificationCode); + +``` + +## PhoneAuthProvider.credentialFromError() + +Returns an [AuthCredential](./auth.authcredential.md#authcredential_class) when passed an error. + +This method works for errors like `auth/account-exists-with-different-credentials`. This is useful for recovering when attempting to set a user's phone number but the number in question is already tied to another account. For example, the following code tries to update the current user's phone number, and if that fails, links the user with the account associated with that number: + +```js +const provider = new PhoneAuthProvider(auth); +const verificationId = await provider.verifyPhoneNumber(number, verifier); +try { + const code = ''; // Prompt the user for the verification code + await updatePhoneNumber( + auth.currentUser, + PhoneAuthProvider.credential(verificationId, code)); +} catch (e) { + if ((e as FirebaseError)?.code === 'auth/account-exists-with-different-credential') { + const cred = PhoneAuthProvider.credentialFromError(e); + await linkWithCredential(auth.currentUser, cred); + } +} + +// At this point, auth.currentUser.phoneNumber === number. + +``` + +Signature: + +```typescript +static credentialFromError(error: FirebaseError): AuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | The error to generate a credential from. | + +Returns: + +[AuthCredential](./auth.authcredential.md#authcredential_class) \| null + +## PhoneAuthProvider.credentialFromResult() + +Generates an [AuthCredential](./auth.authcredential.md#authcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). + +Signature: + +```typescript +static credentialFromResult(userCredential: UserCredential): AuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | + +Returns: + +[AuthCredential](./auth.authcredential.md#authcredential_class) \| null + +## PhoneAuthProvider.verifyPhoneNumber() + +Starts a phone number authentication flow by sending a verification code to the given phone number. + +Signature: + +```typescript +verifyPhoneNumber(phoneOptions: PhoneInfoOptions | string, applicationVerifier: ApplicationVerifier): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| phoneOptions | [PhoneInfoOptions](./auth.md#phoneinfooptions) \| string | | +| applicationVerifier | [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface) | For abuse prevention, this method also requires a [ApplicationVerifier](./auth.applicationverifier.md#applicationverifier_interface). This SDK includes a reCAPTCHA-based implementation, [RecaptchaVerifier](./auth.recaptchaverifier.md#recaptchaverifier_class). | + +Returns: + +Promise<string> + +A Promise for a verification ID that can be passed to [PhoneAuthProvider.credential()](./auth.phoneauthprovider.md#phoneauthprovidercredential) to identify this flow.. + +### Example 1 + + +```javascript +const provider = new PhoneAuthProvider(auth); +const verificationId = await provider.verifyPhoneNumber(phoneNumber, applicationVerifier); +// Obtain verificationCode from the user. +const authCredential = PhoneAuthProvider.credential(verificationId, verificationCode); +const userCredential = await signInWithCredential(auth, authCredential); + +``` + +### Example 2 + +An alternative flow is provided using the `signInWithPhoneNumber` method. + +```javascript +const confirmationResult = signInWithPhoneNumber(auth, phoneNumber, applicationVerifier); +// Obtain verificationCode from the user. +const userCredential = confirmationResult.confirm(verificationCode); + +``` + +### Example + + +```javascript +// 'recaptcha-container' is the ID of an element in the DOM. +const applicationVerifier = new RecaptchaVerifier('recaptcha-container'); +const provider = new PhoneAuthProvider(auth); +const verificationId = await provider.verifyPhoneNumber('+16505550101', applicationVerifier); +// Obtain the verificationCode from the user. +const phoneCredential = PhoneAuthProvider.credential(verificationId, verificationCode); +const userCredential = await signInWithCredential(auth, phoneCredential); + +``` + diff --git a/docs-devsite/auth.phonemultifactorassertion.md b/docs-devsite/auth.phonemultifactorassertion.md new file mode 100644 index 00000000000..1f6afd2410f --- /dev/null +++ b/docs-devsite/auth.phonemultifactorassertion.md @@ -0,0 +1,21 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# PhoneMultiFactorAssertion interface +The class for asserting ownership of a phone second factor. Provided by [PhoneMultiFactorGenerator.assertion()](./auth.phonemultifactorgenerator.md#phonemultifactorgeneratorassertion). + +Signature: + +```typescript +export interface PhoneMultiFactorAssertion extends MultiFactorAssertion +``` +Extends: [MultiFactorAssertion](./auth.multifactorassertion.md#multifactorassertion_interface) + diff --git a/docs-devsite/auth.phonemultifactorenrollinfooptions.md b/docs-devsite/auth.phonemultifactorenrollinfooptions.md new file mode 100644 index 00000000000..f36cfc29d8d --- /dev/null +++ b/docs-devsite/auth.phonemultifactorenrollinfooptions.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# PhoneMultiFactorEnrollInfoOptions interface +Options used for enrolling a second factor. + +Signature: + +```typescript +export interface PhoneMultiFactorEnrollInfoOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [phoneNumber](./auth.phonemultifactorenrollinfooptions.md#phonemultifactorenrollinfooptionsphonenumber) | string | Phone number to send a verification code to. | +| [session](./auth.phonemultifactorenrollinfooptions.md#phonemultifactorenrollinfooptionssession) | [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) | The [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) obtained via [MultiFactorUser.getSession()](./auth.multifactoruser.md#multifactorusergetsession). | + +## PhoneMultiFactorEnrollInfoOptions.phoneNumber + +Phone number to send a verification code to. + +Signature: + +```typescript +phoneNumber: string; +``` + +## PhoneMultiFactorEnrollInfoOptions.session + +The [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) obtained via [MultiFactorUser.getSession()](./auth.multifactoruser.md#multifactorusergetsession). + +Signature: + +```typescript +session: MultiFactorSession; +``` diff --git a/docs-devsite/auth.phonemultifactorgenerator.md b/docs-devsite/auth.phonemultifactorgenerator.md new file mode 100644 index 00000000000..a59d34814bf --- /dev/null +++ b/docs-devsite/auth.phonemultifactorgenerator.md @@ -0,0 +1,64 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# PhoneMultiFactorGenerator class +Provider for generating a [PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface). + +Signature: + +```typescript +export declare class PhoneMultiFactorGenerator +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [FACTOR\_ID](./auth.phonemultifactorgenerator.md#phonemultifactorgeneratorfactor_id) | static | string | The identifier of the phone second factor: phone. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [assertion(credential)](./auth.phonemultifactorgenerator.md#phonemultifactorgeneratorassertion) | static | Provides a [PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface) to confirm ownership of the phone second factor. | + +## PhoneMultiFactorGenerator.FACTOR\_ID + +The identifier of the phone second factor: `phone`. + +Signature: + +```typescript +static FACTOR_ID: string; +``` + +## PhoneMultiFactorGenerator.assertion() + +Provides a [PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface) to confirm ownership of the phone second factor. + +Signature: + +```typescript +static assertion(credential: PhoneAuthCredential): PhoneMultiFactorAssertion; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| credential | [PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class) | | + +Returns: + +[PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface) + +A [PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface) which can be used with [MultiFactorResolver.resolveSignIn()](./auth.multifactorresolver.md#multifactorresolverresolvesignin) + diff --git a/docs-devsite/auth.phonemultifactorinfo.md b/docs-devsite/auth.phonemultifactorinfo.md new file mode 100644 index 00000000000..c12c72b8a55 --- /dev/null +++ b/docs-devsite/auth.phonemultifactorinfo.md @@ -0,0 +1,36 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# PhoneMultiFactorInfo interface +The subclass of the [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) interface for phone number second factors. The `factorId` of this second factor is [FactorId](./auth.md#factorid).PHONE. + +Signature: + +```typescript +export interface PhoneMultiFactorInfo extends MultiFactorInfo +``` +Extends: [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [phoneNumber](./auth.phonemultifactorinfo.md#phonemultifactorinfophonenumber) | string | The phone number associated with the current second factor. | + +## PhoneMultiFactorInfo.phoneNumber + +The phone number associated with the current second factor. + +Signature: + +```typescript +readonly phoneNumber: string; +``` diff --git a/docs-devsite/auth.phonemultifactorsignininfooptions.md b/docs-devsite/auth.phonemultifactorsignininfooptions.md new file mode 100644 index 00000000000..592ef7118b3 --- /dev/null +++ b/docs-devsite/auth.phonemultifactorsignininfooptions.md @@ -0,0 +1,61 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# PhoneMultiFactorSignInInfoOptions interface +Options used for signing in with a second factor. + +Signature: + +```typescript +export interface PhoneMultiFactorSignInInfoOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [multiFactorHint](./auth.phonemultifactorsignininfooptions.md#phonemultifactorsignininfooptionsmultifactorhint) | [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) | The [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) obtained via [MultiFactorResolver.hints](./auth.multifactorresolver.md#multifactorresolverhints).One of multiFactorHint or multiFactorUid is required. | +| [multiFactorUid](./auth.phonemultifactorsignininfooptions.md#phonemultifactorsignininfooptionsmultifactoruid) | string | The uid of the second factor.One of multiFactorHint or multiFactorUid is required. | +| [session](./auth.phonemultifactorsignininfooptions.md#phonemultifactorsignininfooptionssession) | [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) | The [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) obtained via [MultiFactorResolver.session](./auth.multifactorresolver.md#multifactorresolversession). | + +## PhoneMultiFactorSignInInfoOptions.multiFactorHint + +The [MultiFactorInfo](./auth.multifactorinfo.md#multifactorinfo_interface) obtained via [MultiFactorResolver.hints](./auth.multifactorresolver.md#multifactorresolverhints). + +One of `multiFactorHint` or `multiFactorUid` is required. + +Signature: + +```typescript +multiFactorHint?: MultiFactorInfo; +``` + +## PhoneMultiFactorSignInInfoOptions.multiFactorUid + +The uid of the second factor. + +One of `multiFactorHint` or `multiFactorUid` is required. + +Signature: + +```typescript +multiFactorUid?: string; +``` + +## PhoneMultiFactorSignInInfoOptions.session + +The [MultiFactorSession](./auth.multifactorsession.md#multifactorsession_interface) obtained via [MultiFactorResolver.session](./auth.multifactorresolver.md#multifactorresolversession). + +Signature: + +```typescript +session: MultiFactorSession; +``` diff --git a/docs-devsite/auth.phonesinglefactorinfooptions.md b/docs-devsite/auth.phonesinglefactorinfooptions.md new file mode 100644 index 00000000000..f7846d0db42 --- /dev/null +++ b/docs-devsite/auth.phonesinglefactorinfooptions.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# PhoneSingleFactorInfoOptions interface +Options used for single-factor sign-in. + +Signature: + +```typescript +export interface PhoneSingleFactorInfoOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [phoneNumber](./auth.phonesinglefactorinfooptions.md#phonesinglefactorinfooptionsphonenumber) | string | Phone number to send a verification code to. | + +## PhoneSingleFactorInfoOptions.phoneNumber + +Phone number to send a verification code to. + +Signature: + +```typescript +phoneNumber: string; +``` diff --git a/docs-devsite/auth.popupredirectresolver.md b/docs-devsite/auth.popupredirectresolver.md new file mode 100644 index 00000000000..67c3274847c --- /dev/null +++ b/docs-devsite/auth.popupredirectresolver.md @@ -0,0 +1,19 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# PopupRedirectResolver interface +A resolver used for handling DOM specific operations like [signInWithPopup()](./auth.md#signinwithpopup) or [signInWithRedirect()](./auth.md#signinwithredirect). + +Signature: + +```typescript +export interface PopupRedirectResolver +``` diff --git a/docs-devsite/auth.reactnativeasyncstorage.md b/docs-devsite/auth.reactnativeasyncstorage.md new file mode 100644 index 00000000000..231e7d2ed31 --- /dev/null +++ b/docs-devsite/auth.reactnativeasyncstorage.md @@ -0,0 +1,89 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ReactNativeAsyncStorage interface +Interface for a supplied `AsyncStorage`. + +Signature: + +```typescript +export interface ReactNativeAsyncStorage +``` + +## Methods + +| Method | Description | +| --- | --- | +| [getItem(key)](./auth.reactnativeasyncstorage.md#reactnativeasyncstoragegetitem) | Retrieve an item from storage. | +| [removeItem(key)](./auth.reactnativeasyncstorage.md#reactnativeasyncstorageremoveitem) | Remove an item from storage. | +| [setItem(key, value)](./auth.reactnativeasyncstorage.md#reactnativeasyncstoragesetitem) | Persist an item in storage. | + +## ReactNativeAsyncStorage.getItem() + +Retrieve an item from storage. + +Signature: + +```typescript +getItem(key: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| key | string | storage key. | + +Returns: + +Promise<string \| null> + +## ReactNativeAsyncStorage.removeItem() + +Remove an item from storage. + +Signature: + +```typescript +removeItem(key: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| key | string | storage key. | + +Returns: + +Promise<void> + +## ReactNativeAsyncStorage.setItem() + +Persist an item in storage. + +Signature: + +```typescript +setItem(key: string, value: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| key | string | storage key. | +| value | string | storage value. | + +Returns: + +Promise<void> + diff --git a/docs-devsite/auth.recaptchaparameters.md b/docs-devsite/auth.recaptchaparameters.md new file mode 100644 index 00000000000..5d70f1826eb --- /dev/null +++ b/docs-devsite/auth.recaptchaparameters.md @@ -0,0 +1,23 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# RecaptchaParameters interface +Interface representing reCAPTCHA parameters. + +See the \[reCAPTCHA docs\](https://developers.google.com/recaptcha/docs/display\#render\_param) for the list of accepted parameters. All parameters are accepted except for `sitekey`: Firebase Auth provisions a reCAPTCHA for each project and will configure the site key upon rendering. + +For an invisible reCAPTCHA, set the `size` key to `invisible`. + +Signature: + +```typescript +export interface RecaptchaParameters +``` diff --git a/docs-devsite/auth.recaptchaverifier.md b/docs-devsite/auth.recaptchaverifier.md new file mode 100644 index 00000000000..4f32d489aed --- /dev/null +++ b/docs-devsite/auth.recaptchaverifier.md @@ -0,0 +1,116 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# RecaptchaVerifier class +An [reCAPTCHA](https://www.google.com/recaptcha/)-based application verifier. + +Signature: + +```typescript +export declare class RecaptchaVerifier implements ApplicationVerifierInternal +``` +Implements: ApplicationVerifierInternal + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(containerOrId, parameters, authExtern)](./auth.recaptchaverifier.md#recaptchaverifierconstructor) | | Constructs a new instance of the RecaptchaVerifier class | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./auth.recaptchaverifier.md#recaptchaverifiertype) | | (not declared) | The application verifier type. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [clear()](./auth.recaptchaverifier.md#recaptchaverifierclear) | | Clears the reCAPTCHA widget from the page and destroys the instance. | +| [render()](./auth.recaptchaverifier.md#recaptchaverifierrender) | | Renders the reCAPTCHA widget on the page. | +| [verify()](./auth.recaptchaverifier.md#recaptchaverifierverify) | | Waits for the user to solve the reCAPTCHA and resolves with the reCAPTCHA token. | + +## RecaptchaVerifier.(constructor) + +Constructs a new instance of the `RecaptchaVerifier` class + +Check the reCAPTCHA docs for a comprehensive list. All parameters are accepted except for the sitekey. Firebase Auth backend provisions a reCAPTCHA for each project and will configure this upon rendering. For an invisible reCAPTCHA, a size key must have the value 'invisible'. + +Signature: + +```typescript +constructor(containerOrId: HTMLElement | string, parameters: RecaptchaParameters, authExtern: Auth); +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| containerOrId | HTMLElement \| string | The reCAPTCHA container parameter. | +| parameters | [RecaptchaParameters](./auth.recaptchaparameters.md#recaptchaparameters_interface) | The optional reCAPTCHA parameters. | +| authExtern | [Auth](./auth.auth.md#auth_interface) | The corresponding Firebase [Auth](./auth.auth.md#auth_interface) instance. | + +## RecaptchaVerifier.type + +The application verifier type. + +For a reCAPTCHA verifier, this is 'recaptcha'. + +Signature: + +```typescript +readonly type = "recaptcha"; +``` + +## RecaptchaVerifier.clear() + +Clears the reCAPTCHA widget from the page and destroys the instance. + +Signature: + +```typescript +clear(): void; +``` +Returns: + +void + +## RecaptchaVerifier.render() + +Renders the reCAPTCHA widget on the page. + +Signature: + +```typescript +render(): Promise; +``` +Returns: + +Promise<number> + +A Promise that resolves with the reCAPTCHA widget ID. + +## RecaptchaVerifier.verify() + +Waits for the user to solve the reCAPTCHA and resolves with the reCAPTCHA token. + +Signature: + +```typescript +verify(): Promise; +``` +Returns: + +Promise<string> + +A Promise for the reCAPTCHA token. + diff --git a/docs-devsite/auth.samlauthprovider.md b/docs-devsite/auth.samlauthprovider.md new file mode 100644 index 00000000000..d25dd1999ed --- /dev/null +++ b/docs-devsite/auth.samlauthprovider.md @@ -0,0 +1,119 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# SAMLAuthProvider class +An [AuthProvider](./auth.authprovider.md#authprovider_interface) for SAML. + +Signature: + +```typescript +export declare class SAMLAuthProvider extends FederatedAuthProvider +``` +Extends: FederatedAuthProvider + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(providerId)](./auth.samlauthprovider.md#samlauthproviderconstructor) | | Constructor. The providerId must start with "saml." | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [credentialFromError(error)](./auth.samlauthprovider.md#samlauthprovidercredentialfromerror) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. | +| [credentialFromJSON(json)](./auth.samlauthprovider.md#samlauthprovidercredentialfromjson) | static | Creates an [AuthCredential](./auth.authcredential.md#authcredential_class) from a JSON string or a plain object. | +| [credentialFromResult(userCredential)](./auth.samlauthprovider.md#samlauthprovidercredentialfromresult) | static | Generates an [AuthCredential](./auth.authcredential.md#authcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface) after a successful SAML flow completes. | + +## SAMLAuthProvider.(constructor) + +Constructor. The providerId must start with "saml." + +Signature: + +```typescript +constructor(providerId: string); +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| providerId | string | SAML provider ID. | + +## SAMLAuthProvider.credentialFromError() + +Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. + +Signature: + +```typescript +static credentialFromError(error: FirebaseError): AuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | | + +Returns: + +[AuthCredential](./auth.authcredential.md#authcredential_class) \| null + +## SAMLAuthProvider.credentialFromJSON() + +Creates an [AuthCredential](./auth.authcredential.md#authcredential_class) from a JSON string or a plain object. + +Signature: + +```typescript +static credentialFromJSON(json: string | object): AuthCredential; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| json | string \| object | A plain object or a JSON string | + +Returns: + +[AuthCredential](./auth.authcredential.md#authcredential_class) + +## SAMLAuthProvider.credentialFromResult() + +Generates an [AuthCredential](./auth.authcredential.md#authcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface) after a successful SAML flow completes. + +For example, to get an [AuthCredential](./auth.authcredential.md#authcredential_class), you could write the following code: + +```js +const userCredential = await signInWithPopup(auth, samlProvider); +const credential = SAMLAuthProvider.credentialFromResult(userCredential); + +``` + +Signature: + +```typescript +static credentialFromResult(userCredential: UserCredential): AuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | + +Returns: + +[AuthCredential](./auth.authcredential.md#authcredential_class) \| null + diff --git a/docs-devsite/auth.twitterauthprovider.md b/docs-devsite/auth.twitterauthprovider.md new file mode 100644 index 00000000000..9ae64b6bdaf --- /dev/null +++ b/docs-devsite/auth.twitterauthprovider.md @@ -0,0 +1,173 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# TwitterAuthProvider class +Provider for generating an [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) for [ProviderId](./auth.md#providerid).TWITTER. + +Signature: + +```typescript +export declare class TwitterAuthProvider extends BaseOAuthProvider +``` +Extends: BaseOAuthProvider + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)()](./auth.twitterauthprovider.md#twitterauthproviderconstructor) | | Constructs a new instance of the TwitterAuthProvider class | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [PROVIDER\_ID](./auth.twitterauthprovider.md#twitterauthproviderprovider_id) | static | 'twitter.com' | Always set to [ProviderId](./auth.md#providerid).TWITTER. | +| [TWITTER\_SIGN\_IN\_METHOD](./auth.twitterauthprovider.md#twitterauthprovidertwitter_sign_in_method) | static | 'twitter.com' | Always set to [SignInMethod](./auth.md#signinmethod).TWITTER. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [credential(token, secret)](./auth.twitterauthprovider.md#twitterauthprovidercredential) | static | Creates a credential for Twitter. | +| [credentialFromError(error)](./auth.twitterauthprovider.md#twitterauthprovidercredentialfromerror) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. | +| [credentialFromResult(userCredential)](./auth.twitterauthprovider.md#twitterauthprovidercredentialfromresult) | static | Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). | + +## TwitterAuthProvider.(constructor) + +Constructs a new instance of the `TwitterAuthProvider` class + +Signature: + +```typescript +constructor(); +``` + +## TwitterAuthProvider.PROVIDER\_ID + +Always set to [ProviderId](./auth.md#providerid).TWITTER. + +Signature: + +```typescript +static readonly PROVIDER_ID: 'twitter.com'; +``` + +## TwitterAuthProvider.TWITTER\_SIGN\_IN\_METHOD + +Always set to [SignInMethod](./auth.md#signinmethod).TWITTER. + +Signature: + +```typescript +static readonly TWITTER_SIGN_IN_METHOD: 'twitter.com'; +``` + +## TwitterAuthProvider.credential() + +Creates a credential for Twitter. + +Signature: + +```typescript +static credential(token: string, secret: string): OAuthCredential; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| token | string | Twitter access token. | +| secret | string | Twitter secret. | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) + +## TwitterAuthProvider.credentialFromError() + +Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [AuthError](./auth.autherror.md#autherror_interface) which was thrown during a sign-in, link, or reauthenticate operation. + +Signature: + +```typescript +static credentialFromError(error: FirebaseError): OAuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| error | [FirebaseError](./util.firebaseerror.md#firebaseerror_class) | | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null + +## TwitterAuthProvider.credentialFromResult() + +Used to extract the underlying [OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) from a [UserCredential](./auth.usercredential.md#usercredential_interface). + +Signature: + +```typescript +static credentialFromResult(userCredential: UserCredential): OAuthCredential | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| userCredential | [UserCredential](./auth.usercredential.md#usercredential_interface) | The user credential. | + +Returns: + +[OAuthCredential](./auth.oauthcredential.md#oauthcredential_class) \| null + +### Example 1 + + +```javascript +// Sign in using a redirect. +const provider = new TwitterAuthProvider(); +// Start a sign in process for an unauthenticated user. +await signInWithRedirect(auth, provider); +// This will trigger a full page redirect away from your app + +// After returning from the redirect when your app initializes you can obtain the result +const result = await getRedirectResult(auth); +if (result) { + // This is the signed-in user + const user = result.user; + // This gives you a Twitter Access Token and Secret. + const credential = TwitterAuthProvider.credentialFromResult(result); + const token = credential.accessToken; + const secret = credential.secret; +} + +``` + +### Example 2 + + +```javascript +// Sign in using a popup. +const provider = new TwitterAuthProvider(); +const result = await signInWithPopup(auth, provider); + +// The signed-in user info. +const user = result.user; +// This gives you a Twitter Access Token and Secret. +const credential = TwitterAuthProvider.credentialFromResult(result); +const token = credential.accessToken; +const secret = credential.secret; + +``` + diff --git a/docs-devsite/auth.user.md b/docs-devsite/auth.user.md new file mode 100644 index 00000000000..18a56a45901 --- /dev/null +++ b/docs-devsite/auth.user.md @@ -0,0 +1,204 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# User interface +A user account. + +Signature: + +```typescript +export interface User extends UserInfo +``` +Extends: [UserInfo](./auth.userinfo.md#userinfo_interface) + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [emailVerified](./auth.user.md#useremailverified) | boolean | Whether the email has been verified with [sendEmailVerification()](./auth.md#sendemailverification) and [applyActionCode()](./auth.md#applyactioncode). | +| [isAnonymous](./auth.user.md#userisanonymous) | boolean | Whether the user is authenticated using the [ProviderId](./auth.md#providerid).ANONYMOUS provider. | +| [metadata](./auth.user.md#usermetadata) | [UserMetadata](./auth.usermetadata.md#usermetadata_interface) | Additional metadata around user creation and sign-in times. | +| [providerData](./auth.user.md#userproviderdata) | [UserInfo](./auth.userinfo.md#userinfo_interface)\[\] | Additional per provider such as displayName and profile information. | +| [refreshToken](./auth.user.md#userrefreshtoken) | string | Refresh token used to reauthenticate the user. Avoid using this directly and prefer [User.getIdToken()](./auth.user.md#usergetidtoken) to refresh the ID token instead. | +| [tenantId](./auth.user.md#usertenantid) | string \| null | The user's tenant ID. | + +## Methods + +| Method | Description | +| --- | --- | +| [delete()](./auth.user.md#userdelete) | Deletes and signs out the user. | +| [getIdToken(forceRefresh)](./auth.user.md#usergetidtoken) | Returns a JSON Web Token (JWT) used to identify the user to a Firebase service. | +| [getIdTokenResult(forceRefresh)](./auth.user.md#usergetidtokenresult) | Returns a deserialized JSON Web Token (JWT) used to identitfy the user to a Firebase service. | +| [reload()](./auth.user.md#userreload) | Refreshes the user, if signed in. | +| [toJSON()](./auth.user.md#usertojson) | Returns a JSON-serializable representation of this object. | + +## User.emailVerified + +Whether the email has been verified with [sendEmailVerification()](./auth.md#sendemailverification) and [applyActionCode()](./auth.md#applyactioncode). + +Signature: + +```typescript +readonly emailVerified: boolean; +``` + +## User.isAnonymous + +Whether the user is authenticated using the [ProviderId](./auth.md#providerid).ANONYMOUS provider. + +Signature: + +```typescript +readonly isAnonymous: boolean; +``` + +## User.metadata + +Additional metadata around user creation and sign-in times. + +Signature: + +```typescript +readonly metadata: UserMetadata; +``` + +## User.providerData + +Additional per provider such as displayName and profile information. + +Signature: + +```typescript +readonly providerData: UserInfo[]; +``` + +## User.refreshToken + +Refresh token used to reauthenticate the user. Avoid using this directly and prefer [User.getIdToken()](./auth.user.md#usergetidtoken) to refresh the ID token instead. + +Signature: + +```typescript +readonly refreshToken: string; +``` + +## User.tenantId + +The user's tenant ID. + +This is a read-only property, which indicates the tenant ID used to sign in the user. This is null if the user is signed in from the parent project. + +Signature: + +```typescript +readonly tenantId: string | null; +``` + +### Example + + +```javascript +// Set the tenant ID on Auth instance. +auth.tenantId = 'TENANT_PROJECT_ID'; + +// All future sign-in request now include tenant ID. +const result = await signInWithEmailAndPassword(auth, email, password); +// result.user.tenantId should be 'TENANT_PROJECT_ID'. + +``` + +## User.delete() + +Deletes and signs out the user. + +Important: this is a security-sensitive operation that requires the user to have recently signed in. If this requirement isn't met, ask the user to authenticate again and then call one of the reauthentication methods like [reauthenticateWithCredential()](./auth.md#reauthenticatewithcredential). + +Signature: + +```typescript +delete(): Promise; +``` +Returns: + +Promise<void> + +## User.getIdToken() + +Returns a JSON Web Token (JWT) used to identify the user to a Firebase service. + +Returns the current token if it has not expired or if it will not expire in the next five minutes. Otherwise, this will refresh the token and return a new one. + +Signature: + +```typescript +getIdToken(forceRefresh?: boolean): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| forceRefresh | boolean | Force refresh regardless of token expiration. | + +Returns: + +Promise<string> + +## User.getIdTokenResult() + +Returns a deserialized JSON Web Token (JWT) used to identitfy the user to a Firebase service. + +Returns the current token if it has not expired or if it will not expire in the next five minutes. Otherwise, this will refresh the token and return a new one. + +Signature: + +```typescript +getIdTokenResult(forceRefresh?: boolean): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| forceRefresh | boolean | Force refresh regardless of token expiration. | + +Returns: + +Promise<[IdTokenResult](./auth.idtokenresult.md#idtokenresult_interface)> + +## User.reload() + +Refreshes the user, if signed in. + +Signature: + +```typescript +reload(): Promise; +``` +Returns: + +Promise<void> + +## User.toJSON() + +Returns a JSON-serializable representation of this object. + +Signature: + +```typescript +toJSON(): object; +``` +Returns: + +object + +A JSON-serializable representation of this object. + diff --git a/docs-devsite/auth.usercredential.md b/docs-devsite/auth.usercredential.md new file mode 100644 index 00000000000..665a1ec253e --- /dev/null +++ b/docs-devsite/auth.usercredential.md @@ -0,0 +1,59 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# UserCredential interface +A structure containing a [User](./auth.user.md#user_interface), the [OperationType](./auth.md#operationtype), and the provider ID. + +`operationType` could be [OperationType](./auth.md#operationtype).SIGN\_IN for a sign-in operation, [OperationType](./auth.md#operationtype).LINK for a linking operation and [OperationType](./auth.md#operationtype).REAUTHENTICATE for a reauthentication operation. + +Signature: + +```typescript +export interface UserCredential +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [operationType](./auth.usercredential.md#usercredentialoperationtype) | typeof [OperationTypeMap](./auth.md#operationtype)\[keyof typeof [OperationTypeMap](./auth.md#operationtype)\] | The type of operation which was used to authenticate the user (such as sign-in or link). | +| [providerId](./auth.usercredential.md#usercredentialproviderid) | string \| null | The provider which was used to authenticate the user. | +| [user](./auth.usercredential.md#usercredentialuser) | [User](./auth.user.md#user_interface) | The user authenticated by this credential. | + +## UserCredential.operationType + +The type of operation which was used to authenticate the user (such as sign-in or link). + +Signature: + +```typescript +operationType: typeof OperationTypeMap[keyof typeof OperationTypeMap]; +``` + +## UserCredential.providerId + +The provider which was used to authenticate the user. + +Signature: + +```typescript +providerId: string | null; +``` + +## UserCredential.user + +The user authenticated by this credential. + +Signature: + +```typescript +user: User; +``` diff --git a/docs-devsite/auth.userinfo.md b/docs-devsite/auth.userinfo.md new file mode 100644 index 00000000000..7b49dc65f9c --- /dev/null +++ b/docs-devsite/auth.userinfo.md @@ -0,0 +1,92 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# UserInfo interface +User profile information, visible only to the Firebase project's apps. + +Signature: + +```typescript +export interface UserInfo +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [displayName](./auth.userinfo.md#userinfodisplayname) | string \| null | The display name of the user. | +| [email](./auth.userinfo.md#userinfoemail) | string \| null | The email of the user. | +| [phoneNumber](./auth.userinfo.md#userinfophonenumber) | string \| null | The phone number normalized based on the E.164 standard (e.g. +16505550101) for the user. | +| [photoURL](./auth.userinfo.md#userinfophotourl) | string \| null | The profile photo URL of the user. | +| [providerId](./auth.userinfo.md#userinfoproviderid) | string | The provider used to authenticate the user. | +| [uid](./auth.userinfo.md#userinfouid) | string | The user's unique ID, scoped to the project. | + +## UserInfo.displayName + +The display name of the user. + +Signature: + +```typescript +readonly displayName: string | null; +``` + +## UserInfo.email + +The email of the user. + +Signature: + +```typescript +readonly email: string | null; +``` + +## UserInfo.phoneNumber + +The phone number normalized based on the E.164 standard (e.g. +16505550101) for the user. + +This is null if the user has no phone credential linked to the account. + +Signature: + +```typescript +readonly phoneNumber: string | null; +``` + +## UserInfo.photoURL + +The profile photo URL of the user. + +Signature: + +```typescript +readonly photoURL: string | null; +``` + +## UserInfo.providerId + +The provider used to authenticate the user. + +Signature: + +```typescript +readonly providerId: string; +``` + +## UserInfo.uid + +The user's unique ID, scoped to the project. + +Signature: + +```typescript +readonly uid: string; +``` diff --git a/docs-devsite/auth.usermetadata.md b/docs-devsite/auth.usermetadata.md new file mode 100644 index 00000000000..bb65b30eff5 --- /dev/null +++ b/docs-devsite/auth.usermetadata.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# UserMetadata interface +Interface representing a user's metadata. + +Signature: + +```typescript +export interface UserMetadata +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [creationTime](./auth.usermetadata.md#usermetadatacreationtime) | string | Time the user was created. | +| [lastSignInTime](./auth.usermetadata.md#usermetadatalastsignintime) | string | Time the user last signed in. | + +## UserMetadata.creationTime + +Time the user was created. + +Signature: + +```typescript +readonly creationTime?: string; +``` + +## UserMetadata.lastSignInTime + +Time the user last signed in. + +Signature: + +```typescript +readonly lastSignInTime?: string; +``` diff --git a/docs-devsite/database.database.md b/docs-devsite/database.database.md new file mode 100644 index 00000000000..62ce4f8a420 --- /dev/null +++ b/docs-devsite/database.database.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Database class +Class representing a Firebase Realtime Database. + +Signature: + +```typescript +export declare class Database +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [app](./database.database.md#databaseapp) | | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this Realtime Database instance. | +| [type](./database.database.md#databasetype) | | (not declared) | Represents a Database instance. | + +## Database.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this Realtime Database instance. + +Signature: + +```typescript +readonly app: FirebaseApp; +``` + +## Database.type + +Represents a `Database` instance. + +Signature: + +```typescript +readonly 'type' = "database"; +``` diff --git a/docs-devsite/database.databasereference.md b/docs-devsite/database.databasereference.md new file mode 100644 index 00000000000..13f19a3bf4f --- /dev/null +++ b/docs-devsite/database.databasereference.md @@ -0,0 +1,68 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# DatabaseReference interface +A `DatabaseReference` represents a specific location in your Database and can be used for reading or writing data to that Database location. + +You can reference the root or child location in your Database by calling `ref()` or `ref("child/path")`. + +Writing is done with the `set()` method and reading can be done with the `on*()` method. See [https://firebase.google.com/docs/database/web/read-and-write](https://firebase.google.com/docs/database/web/read-and-write) + +Signature: + +```typescript +export declare interface DatabaseReference extends Query +``` +Extends: [Query](./database.query.md#query_interface) + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [key](./database.databasereference.md#databasereferencekey) | string \| null | The last part of the DatabaseReference's path.For example, "ada" is the key for https://<DATABASE_NAME>.firebaseio.com/users/ada.The key of a root DatabaseReference is null. | +| [parent](./database.databasereference.md#databasereferenceparent) | [DatabaseReference](./database.databasereference.md#databasereference_interface) \| null | The parent location of a DatabaseReference.The parent of a root DatabaseReference is null. | +| [root](./database.databasereference.md#databasereferenceroot) | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The root DatabaseReference of the Database. | + +## DatabaseReference.key + +The last part of the `DatabaseReference`'s path. + +For example, `"ada"` is the key for `https://.firebaseio.com/users/ada`. + +The key of a root `DatabaseReference` is `null`. + +Signature: + +```typescript +readonly key: string | null; +``` + +## DatabaseReference.parent + +The parent location of a `DatabaseReference`. + +The parent of a root `DatabaseReference` is `null`. + +Signature: + +```typescript +readonly parent: DatabaseReference | null; +``` + +## DatabaseReference.root + +The root `DatabaseReference` of the Database. + +Signature: + +```typescript +readonly root: DatabaseReference; +``` diff --git a/docs-devsite/database.datasnapshot.md b/docs-devsite/database.datasnapshot.md new file mode 100644 index 00000000000..35e983def87 --- /dev/null +++ b/docs-devsite/database.datasnapshot.md @@ -0,0 +1,237 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# DataSnapshot class +A `DataSnapshot` contains data from a Database location. + +Any time you read data from the Database, you receive the data as a `DataSnapshot`. A `DataSnapshot` is passed to the event callbacks you attach with `on()` or `once()`. You can extract the contents of the snapshot as a JavaScript object by calling the `val()` method. Alternatively, you can traverse into the snapshot by calling `child()` to return child snapshots (which you could then call `val()` on). + +A `DataSnapshot` is an efficiently generated, immutable copy of the data at a Database location. It cannot be modified and will never change (to modify data, you always call the `set()` method on a `Reference` directly). + +Signature: + +```typescript +export declare class DataSnapshot +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [key](./database.datasnapshot.md#datasnapshotkey) | | string \| null | The key (last part of the path) of the location of this DataSnapshot.The last token in a Database location is considered its key. For example, "ada" is the key for the /users/ada/ node. Accessing the key on any DataSnapshot will return the key for the location that generated it. However, accessing the key on the root URL of a Database will return null. | +| [priority](./database.datasnapshot.md#datasnapshotpriority) | | string \| number \| null | Gets the priority value of the data in this DataSnapshot.Applications need not use priority but can order collections by ordinary properties (see [Sorting and filtering data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) ). | +| [ref](./database.datasnapshot.md#datasnapshotref) | | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location of this DataSnapshot. | +| [size](./database.datasnapshot.md#datasnapshotsize) | | number | Returns the number of child properties of this DataSnapshot. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [child(path)](./database.datasnapshot.md#datasnapshotchild) | | Gets another DataSnapshot for the location at the specified relative path.Passing a relative path to the child() method of a DataSnapshot returns another DataSnapshot for the location at the specified relative path. The relative path can either be a simple child name (for example, "ada") or a deeper, slash-separated path (for example, "ada/name/first"). If the child location has no data, an empty DataSnapshot (that is, a DataSnapshot whose value is null) is returned. | +| [exists()](./database.datasnapshot.md#datasnapshotexists) | | Returns true if this DataSnapshot contains any data. It is slightly more efficient than using snapshot.val() !== null. | +| [exportVal()](./database.datasnapshot.md#datasnapshotexportval) | | Exports the entire contents of the DataSnapshot as a JavaScript object.The exportVal() method is similar to val(), except priority information is included (if available), making it suitable for backing up your data. | +| [forEach(action)](./database.datasnapshot.md#datasnapshotforeach) | | Enumerates the top-level children in the DataSnapshot.Because of the way JavaScript objects work, the ordering of data in the JavaScript object returned by val() is not guaranteed to match the ordering on the server nor the ordering of onChildAdded() events. That is where forEach() comes in handy. It guarantees the children of a DataSnapshot will be iterated in their query order.If no explicit orderBy*() method is used, results are returned ordered by key (unless priorities are used, in which case, results are returned by priority). | +| [hasChild(path)](./database.datasnapshot.md#datasnapshothaschild) | | Returns true if the specified child path has (non-null) data. | +| [hasChildren()](./database.datasnapshot.md#datasnapshothaschildren) | | Returns whether or not the DataSnapshot has any non-null child properties.You can use hasChildren() to determine if a DataSnapshot has any children. If it does, you can enumerate them using forEach(). If it doesn't, then either this snapshot contains a primitive value (which can be retrieved with val()) or it is empty (in which case, val() will return null). | +| [toJSON()](./database.datasnapshot.md#datasnapshottojson) | | Returns a JSON-serializable representation of this object. | +| [val()](./database.datasnapshot.md#datasnapshotval) | | Extracts a JavaScript value from a DataSnapshot.Depending on the data in a DataSnapshot, the val() method may return a scalar type (string, number, or boolean), an array, or an object. It may also return null, indicating that the DataSnapshot is empty (contains no data). | + +## DataSnapshot.key + +The key (last part of the path) of the location of this `DataSnapshot`. + +The last token in a Database location is considered its key. For example, "ada" is the key for the /users/ada/ node. Accessing the key on any `DataSnapshot` will return the key for the location that generated it. However, accessing the key on the root URL of a Database will return `null`. + +Signature: + +```typescript +get key(): string | null; +``` + +## DataSnapshot.priority + +Gets the priority value of the data in this `DataSnapshot`. + +Applications need not use priority but can order collections by ordinary properties (see [Sorting and filtering data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) ). + +Signature: + +```typescript +get priority(): string | number | null; +``` + +## DataSnapshot.ref + +The location of this DataSnapshot. + +Signature: + +```typescript +readonly ref: DatabaseReference; +``` + +## DataSnapshot.size + +Returns the number of child properties of this `DataSnapshot`. + +Signature: + +```typescript +get size(): number; +``` + +## DataSnapshot.child() + +Gets another `DataSnapshot` for the location at the specified relative path. + +Passing a relative path to the `child()` method of a DataSnapshot returns another `DataSnapshot` for the location at the specified relative path. The relative path can either be a simple child name (for example, "ada") or a deeper, slash-separated path (for example, "ada/name/first"). If the child location has no data, an empty `DataSnapshot` (that is, a `DataSnapshot` whose value is `null`) is returned. + +Signature: + +```typescript +child(path: string): DataSnapshot; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| path | string | A relative path to the location of child data. | + +Returns: + +[DataSnapshot](./database.datasnapshot.md#datasnapshot_class) + +## DataSnapshot.exists() + +Returns true if this `DataSnapshot` contains any data. It is slightly more efficient than using `snapshot.val() !== null`. + +Signature: + +```typescript +exists(): boolean; +``` +Returns: + +boolean + +## DataSnapshot.exportVal() + +Exports the entire contents of the DataSnapshot as a JavaScript object. + +The `exportVal()` method is similar to `val()`, except priority information is included (if available), making it suitable for backing up your data. + +Signature: + +```typescript +exportVal(): any; +``` +Returns: + +any + +The DataSnapshot's contents as a JavaScript value (Object, Array, string, number, boolean, or `null`). + +## DataSnapshot.forEach() + +Enumerates the top-level children in the `DataSnapshot`. + +Because of the way JavaScript objects work, the ordering of data in the JavaScript object returned by `val()` is not guaranteed to match the ordering on the server nor the ordering of `onChildAdded()` events. That is where `forEach()` comes in handy. It guarantees the children of a `DataSnapshot` will be iterated in their query order. + +If no explicit `orderBy*()` method is used, results are returned ordered by key (unless priorities are used, in which case, results are returned by priority). + +Signature: + +```typescript +forEach(action: (child: DataSnapshot) => boolean | void): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| action | (child: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => boolean \| void | A function that will be called for each child DataSnapshot. The callback can return true to cancel further enumeration. | + +Returns: + +boolean + +true if enumeration was canceled due to your callback returning true. + +## DataSnapshot.hasChild() + +Returns true if the specified child path has (non-null) data. + +Signature: + +```typescript +hasChild(path: string): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| path | string | A relative path to the location of a potential child. | + +Returns: + +boolean + +`true` if data exists at the specified child path; else `false`. + +## DataSnapshot.hasChildren() + +Returns whether or not the `DataSnapshot` has any non-`null` child properties. + +You can use `hasChildren()` to determine if a `DataSnapshot` has any children. If it does, you can enumerate them using `forEach()`. If it doesn't, then either this snapshot contains a primitive value (which can be retrieved with `val()`) or it is empty (in which case, `val()` will return `null`). + +Signature: + +```typescript +hasChildren(): boolean; +``` +Returns: + +boolean + +true if this snapshot has any children; else false. + +## DataSnapshot.toJSON() + +Returns a JSON-serializable representation of this object. + +Signature: + +```typescript +toJSON(): object | null; +``` +Returns: + +object \| null + +## DataSnapshot.val() + +Extracts a JavaScript value from a `DataSnapshot`. + +Depending on the data in a `DataSnapshot`, the `val()` method may return a scalar type (string, number, or boolean), an array, or an object. It may also return null, indicating that the `DataSnapshot` is empty (contains no data). + +Signature: + +```typescript +val(): any; +``` +Returns: + +any + +The DataSnapshot's contents as a JavaScript value (Object, Array, string, number, boolean, or `null`). + diff --git a/docs-devsite/database.listenoptions.md b/docs-devsite/database.listenoptions.md new file mode 100644 index 00000000000..171067dd020 --- /dev/null +++ b/docs-devsite/database.listenoptions.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ListenOptions interface +An options objects that can be used to customize a listener. + +Signature: + +```typescript +export declare interface ListenOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [onlyOnce](./database.listenoptions.md#listenoptionsonlyonce) | boolean | Whether to remove the listener after its first invocation. | + +## ListenOptions.onlyOnce + +Whether to remove the listener after its first invocation. + +Signature: + +```typescript +readonly onlyOnce?: boolean; +``` diff --git a/docs-devsite/database.md b/docs-devsite/database.md new file mode 100644 index 00000000000..686ca7f8580 --- /dev/null +++ b/docs-devsite/database.md @@ -0,0 +1,1405 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# database package +Firebase Realtime Database + +## Functions + +| Function | Description | +| --- | --- | +| function(app...) | +| [getDatabase(app, url)](./database.md#getdatabase) | Returns the instance of the Realtime Database SDK that is associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). Initializes a new instance with with default settings if no instance exists or if the existing instance uses a custom database URL. | +| function(db...) | +| [connectDatabaseEmulator(db, host, port, options)](./database.md#connectdatabaseemulator) | Modify the provided instance to communicate with the Realtime Database emulator.

Note: This method must be called before performing any other operation. | +| [goOffline(db)](./database.md#gooffline) | Disconnects from the server (all Database operations will be completed offline).The client automatically maintains a persistent connection to the Database server, which will remain active indefinitely and reconnect when disconnected. However, the goOffline() and goOnline() methods may be used to control the client connection in cases where a persistent connection is undesirable.While offline, the client will no longer receive data updates from the Database. However, all Database operations performed locally will continue to immediately fire events, allowing your application to continue behaving normally. Additionally, each operation performed locally will automatically be queued and retried upon reconnection to the Database server.To reconnect to the Database and begin receiving remote events, see goOnline(). | +| [goOnline(db)](./database.md#goonline) | Reconnects to the server and synchronizes the offline Database state with the server state.This method should be used after disabling the active connection with goOffline(). Once reconnected, the client will transmit the proper data and fire the appropriate events so that your client "catches up" automatically. | +| [ref(db, path)](./database.md#ref) | Returns a Reference representing the location in the Database corresponding to the provided path. If no path is provided, the Reference will point to the root of the Database. | +| [refFromURL(db, url)](./database.md#reffromurl) | Returns a Reference representing the location in the Database corresponding to the provided Firebase URL.An exception is thrown if the URL is not a valid Firebase Database URL or it has a different domain than the current Database instance.Note that all query parameters (orderBy, limitToLast, etc.) are ignored and are not applied to the returned Reference. | +| function() | +| [forceLongPolling()](./database.md#forcelongpolling) | Force the use of longPolling instead of websockets. This will be ignored if websocket protocol is used in databaseURL. | +| [forceWebSockets()](./database.md#forcewebsockets) | Force the use of websockets instead of longPolling. | +| [orderByKey()](./database.md#orderbykey) | Creates a new QueryConstraint that orders by the key.Sorts the results of a query by their (ascending) key values.You can read more about orderByKey() in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). | +| [orderByPriority()](./database.md#orderbypriority) | Creates a new QueryConstraint that orders by priority.Applications need not use priority but can order collections by ordinary properties (see [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data) for alternatives to priority. | +| [orderByValue()](./database.md#orderbyvalue) | Creates a new QueryConstraint that orders by value.If the children of a query are all scalar values (string, number, or boolean), you can order the results by their (ascending) values.You can read more about orderByValue() in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). | +| [serverTimestamp()](./database.md#servertimestamp) | Returns a placeholder value for auto-populating the current timestamp (time since the Unix epoch, in milliseconds) as determined by the Firebase servers. | +| function(delta...) | +| [increment(delta)](./database.md#increment) | Returns a placeholder value that can be used to atomically increment the current database value by the provided delta. | +| function(enabled...) | +| [enableLogging(enabled, persistent)](./database.md#enablelogging) | Logs debugging information to the console. | +| function(limit...) | +| [limitToFirst(limit)](./database.md#limittofirst) | Creates a new QueryConstraint that if limited to the first specific number of children.The limitToFirst() method is used to set a maximum number of children to be synced for a given callback. If we set a limit of 100, we will initially only receive up to 100 child_added events. If we have fewer than 100 messages stored in our Database, a child_added event will fire for each message. However, if we have over 100 messages, we will only receive a child_added event for the first 100 ordered messages. As items change, we will receive child_removed events for each item that drops out of the active list so that the total number stays at 100.You can read more about limitToFirst() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | +| [limitToLast(limit)](./database.md#limittolast) | Creates a new QueryConstraint that is limited to return only the last specified number of children.The limitToLast() method is used to set a maximum number of children to be synced for a given callback. If we set a limit of 100, we will initially only receive up to 100 child_added events. If we have fewer than 100 messages stored in our Database, a child_added event will fire for each message. However, if we have over 100 messages, we will only receive a child_added event for the last 100 ordered messages. As items change, we will receive child_removed events for each item that drops out of the active list so that the total number stays at 100.You can read more about limitToLast() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | +| function(logger...) | +| [enableLogging(logger)](./database.md#enablelogging) | Logs debugging information to the console. | +| function(parent...) | +| [child(parent, path)](./database.md#child) | Gets a Reference for the location at the specified relative path.The relative path can either be a simple child name (for example, "ada") or a deeper slash-separated path (for example, "ada/name/first"). | +| [push(parent, value)](./database.md#push) | Generates a new child location using a unique key and returns its Reference.This is the most common pattern for adding data to a collection of items.If you provide a value to push(), the value is written to the generated location. If you don't pass a value, nothing is written to the database and the child remains empty (but you can use the Reference elsewhere).The unique keys generated by push() are ordered by the current time, so the resulting list of items is chronologically sorted. The keys are also designed to be unguessable (they contain 72 random bits of entropy).See [Append to a list of data](https://firebase.google.com/docs/database/web/lists-of-data#append_to_a_list_of_data). See [The 2^120 Ways to Ensure Unique Identifiers](https://firebase.googleblog.com/2015/02/the-2120-ways-to-ensure-unique_68.html). | +| function(path...) | +| [orderByChild(path)](./database.md#orderbychild) | Creates a new QueryConstraint that orders by the specified child key.Queries can only order by one key at a time. Calling orderByChild() multiple times on the same query is an error.Firebase queries allow you to order your data by any child key on the fly. However, if you know in advance what your indexes will be, you can define them via the .indexOn rule in your Security Rules for better performance. See the[https://firebase.google.com/docs/database/security/indexing-data](https://firebase.google.com/docs/database/security/indexing-data) rule for more information.You can read more about orderByChild() in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). | +| function(query...) | +| [get(query)](./database.md#get) | Gets the most up-to-date result for this query. | +| [off(query, eventType, callback)](./database.md#off) | Detaches a callback previously attached with the corresponding on*() (onValue, onChildAdded) listener. Note: This is not the recommended way to remove a listener. Instead, please use the returned callback function from the respective on* callbacks.Detach a callback previously attached with on*(). Calling off() on a parent listener will not automatically remove listeners registered on child nodes, off() must also be called on any child listeners to remove the callback.If a callback is not specified, all callbacks for the specified eventType will be removed. Similarly, if no eventType is specified, all callbacks for the Reference will be removed.Individual listeners can also be removed by invoking their unsubscribe callbacks. | +| [onChildAdded(query, callback, cancelCallback)](./database.md#onchildadded) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildAdded event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The DataSnapshot passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | +| [onChildAdded(query, callback, options)](./database.md#onchildadded) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildAdded event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The DataSnapshot passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | +| [onChildAdded(query, callback, cancelCallback, options)](./database.md#onchildadded) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildAdded event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The DataSnapshot passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | +| [onChildChanged(query, callback, cancelCallback)](./database.md#onchildchanged) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildChanged event will be triggered when the data stored in a child (or any of its descendants) changes. Note that a single child_changed event may represent multiple changes to the child. The DataSnapshot passed to the callback will contain the new child contents. For ordering purposes, the callback is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | +| [onChildChanged(query, callback, options)](./database.md#onchildchanged) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildChanged event will be triggered when the data stored in a child (or any of its descendants) changes. Note that a single child_changed event may represent multiple changes to the child. The DataSnapshot passed to the callback will contain the new child contents. For ordering purposes, the callback is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | +| [onChildChanged(query, callback, cancelCallback, options)](./database.md#onchildchanged) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildChanged event will be triggered when the data stored in a child (or any of its descendants) changes. Note that a single child_changed event may represent multiple changes to the child. The DataSnapshot passed to the callback will contain the new child contents. For ordering purposes, the callback is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | +| [onChildMoved(query, callback, cancelCallback)](./database.md#onchildmoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildMoved event will be triggered when a child's sort order changes such that its position relative to its siblings changes. The DataSnapshot passed to the callback will be for the data of the child that has moved. It is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | +| [onChildMoved(query, callback, options)](./database.md#onchildmoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildMoved event will be triggered when a child's sort order changes such that its position relative to its siblings changes. The DataSnapshot passed to the callback will be for the data of the child that has moved. It is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | +| [onChildMoved(query, callback, cancelCallback, options)](./database.md#onchildmoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildMoved event will be triggered when a child's sort order changes such that its position relative to its siblings changes. The DataSnapshot passed to the callback will be for the data of the child that has moved. It is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or null if it is the first child. | +| [onChildRemoved(query, callback, cancelCallback)](./database.md#onchildremoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildRemoved event will be triggered once every time a child is removed. The DataSnapshot passed into the callback will be the old data for the child that was removed. A child will get removed when either:- a client explicitly calls remove() on that child or one of its ancestors - a client calls set(null) on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) | +| [onChildRemoved(query, callback, options)](./database.md#onchildremoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildRemoved event will be triggered once every time a child is removed. The DataSnapshot passed into the callback will be the old data for the child that was removed. A child will get removed when either:- a client explicitly calls remove() on that child or one of its ancestors - a client calls set(null) on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) | +| [onChildRemoved(query, callback, cancelCallback, options)](./database.md#onchildremoved) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onChildRemoved event will be triggered once every time a child is removed. The DataSnapshot passed into the callback will be the old data for the child that was removed. A child will get removed when either:- a client explicitly calls remove() on that child or one of its ancestors - a client calls set(null) on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) | +| [onValue(query, callback, cancelCallback)](./database.md#onvalue) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onValue event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The DataSnapshot passed to the callback will be for the location at which on() was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty DataSnapshot (val() will return null). | +| [onValue(query, callback, options)](./database.md#onvalue) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onValue event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The DataSnapshot passed to the callback will be for the location at which on() was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty DataSnapshot (val() will return null). | +| [onValue(query, callback, cancelCallback, options)](./database.md#onvalue) | Listens for data changes at a particular location.This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details.An onValue event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The DataSnapshot passed to the callback will be for the location at which on() was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty DataSnapshot (val() will return null). | +| [query(query, queryConstraints)](./database.md#query) | Creates a new immutable instance of Query that is extended to also include additional query constraints. | +| function(ref...) | +| [onDisconnect(ref)](./database.md#ondisconnect) | Returns an OnDisconnect object - see [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information on how to use it. | +| [remove(ref)](./database.md#remove) | Removes the data at this Database location.Any data at child locations will also be deleted.The effect of the remove will be visible immediately and the corresponding event 'value' will be triggered. Synchronization of the remove to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the onComplete callback will be called asynchronously after synchronization has finished. | +| [runTransaction(ref, transactionUpdate, options)](./database.md#runtransaction) | Atomically modifies the data at this location.Atomically modify the data at this location. Unlike a normal set(), which just overwrites the data regardless of its previous value, runTransaction() is used to modify the existing value to a new value, ensuring there are no conflicts with other clients writing to the same location at the same time.To accomplish this, you pass runTransaction() an update function which is used to transform the current value into a new value. If another client writes to the location before your new value is successfully written, your update function will be called again with the new current value, and the write will be retried. This will happen repeatedly until your write succeeds without conflict or you abort the transaction by not returning a value from your update function.Note: Modifying data with set() will cancel any pending transactions at that location, so extreme care should be taken if mixing set() and runTransaction() to update the same data.Note: When using transactions with Security and Firebase Rules in place, be aware that a client needs .read access in addition to .write access in order to perform a transaction. This is because the client-side nature of transactions requires the client to read the data in order to transactionally update it. | +| [set(ref, value)](./database.md#set) | Writes data to this Database location.This will overwrite any data at this location and all child locations.The effect of the write will be visible immediately, and the corresponding events ("value", "child\_added", etc.) will be triggered. Synchronization of the data to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the onComplete callback will be called asynchronously after synchronization has finished.Passing null for the new value is equivalent to calling remove(); namely, all data at this location and all child locations will be deleted.set() will remove any priority stored at this location, so if priority is meant to be preserved, you need to use setWithPriority() instead.Note that modifying data with set() will cancel any pending transactions at that location, so extreme care should be taken if mixing set() and transaction() to modify the same data.A single set() will generate a single "value" event at the location where the set() was performed. | +| [setPriority(ref, priority)](./database.md#setpriority) | Sets a priority for the data at this Database location.Applications need not use priority but can order collections by ordinary properties (see [Sorting and filtering data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) ). | +| [setWithPriority(ref, value, priority)](./database.md#setwithpriority) | Writes data the Database location. Like set() but also specifies the priority for that data.Applications need not use priority but can order collections by ordinary properties (see [Sorting and filtering data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) ). | +| [update(ref, values)](./database.md#update) | Writes multiple values to the Database at once.The values argument contains multiple property-value pairs that will be written to the Database together. Each child property can either be a simple property (for example, "name") or a relative path (for example, "name/first") from the current location to the data to update.As opposed to the set() method, update() can be use to selectively update only the referenced properties at the current location (instead of replacing all the child properties at the current location).The effect of the write will be visible immediately, and the corresponding events ('value', 'child\_added', etc.) will be triggered. Synchronization of the data to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the onComplete callback will be called asynchronously after synchronization has finished.A single update() will generate a single "value" event at the location where the update() was performed, regardless of how many children were modified.Note that modifying data with update() will cancel any pending transactions at that location, so extreme care should be taken if mixing update() and transaction() to modify the same data.Passing null to update() will remove the data at this location.See [Introducing multi-location updates and more](https://firebase.googleblog.com/2015/09/introducing-multi-location-updates-and_86.html). | +| function(value...) | +| [endAt(value, key)](./database.md#endat) | Creates a QueryConstraint with the specified ending point.Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The ending point is inclusive, so children with exactly the specified value will be included in the query. The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have a key name less than or equal to the specified key.You can read more about endAt() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | +| [endBefore(value, key)](./database.md#endbefore) | Creates a QueryConstraint with the specified ending point (exclusive).Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The ending point is exclusive. If only a value is provided, children with a value less than the specified value will be included in the query. If a key is specified, then children must have a value less than or equal to the specified value and a key name less than the specified key. | +| [equalTo(value, key)](./database.md#equalto) | Creates a QueryConstraint that includes children that match the specified value.Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have exactly the specified key as their key name. This can be used to filter result sets with many matches for the same value.You can read more about equalTo() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | +| [startAfter(value, key)](./database.md#startafter) | Creates a QueryConstraint with the specified starting point (exclusive).Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The starting point is exclusive. If only a value is provided, children with a value greater than the specified value will be included in the query. If a key is specified, then children must have a value greater than or equal to the specified value and a a key name greater than the specified key. | +| [startAt(value, key)](./database.md#startat) | Creates a QueryConstraint with the specified starting point.Using startAt(), startAfter(), endBefore(), endAt() and equalTo() allows you to choose arbitrary starting and ending points for your queries.The starting point is inclusive, so children with exactly the specified value will be included in the query. The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have a key name greater than or equal to the specified key.You can read more about startAt() in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). | + +## Classes + +| Class | Description | +| --- | --- | +| [Database](./database.database.md#database_class) | Class representing a Firebase Realtime Database. | +| [DataSnapshot](./database.datasnapshot.md#datasnapshot_class) | A DataSnapshot contains data from a Database location.Any time you read data from the Database, you receive the data as a DataSnapshot. A DataSnapshot is passed to the event callbacks you attach with on() or once(). You can extract the contents of the snapshot as a JavaScript object by calling the val() method. Alternatively, you can traverse into the snapshot by calling child() to return child snapshots (which you could then call val() on).A DataSnapshot is an efficiently generated, immutable copy of the data at a Database location. It cannot be modified and will never change (to modify data, you always call the set() method on a Reference directly). | +| [OnDisconnect](./database.ondisconnect.md#ondisconnect_class) | The onDisconnect class allows you to write or clear data when your client disconnects from the Database server. These updates occur whether your client disconnects cleanly or not, so you can rely on them to clean up data even if a connection is dropped or a client crashes.The onDisconnect class is most commonly used to manage presence in applications where it is useful to detect how many clients are connected and when other clients disconnect. See [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information.To avoid problems when a connection is dropped before the requests can be transferred to the Database server, these functions should be called before writing any data.Note that onDisconnect operations are only triggered once. If you want an operation to occur each time a disconnect occurs, you'll need to re-establish the onDisconnect operations each time you reconnect. | +| [QueryConstraint](./database.queryconstraint.md#queryconstraint_class) | A QueryConstraint is used to narrow the set of documents returned by a Database query. QueryConstraints are created by invoking [endAt()](./database.md#endat), [endBefore()](./database.md#endbefore), [startAt()](./database.md#startat), [startAfter()](./database.md#startafter), [limitToFirst()](./database.md#limittofirst), [limitToLast()](./database.md#limittolast), [orderByChild()](./database.md#orderbychild), [orderByChild()](./database.md#orderbychild), [orderByKey()](./database.md#orderbykey) , [orderByPriority()](./database.md#orderbypriority) , [orderByValue()](./database.md#orderbyvalue) or [equalTo()](./database.md#equalto) and can then be passed to [query()](./database.md#query) to create a new query instance that also contains this QueryConstraint. | +| [TransactionResult](./database.transactionresult.md#transactionresult_class) | A type for the resolve value of [runTransaction()](./database.md#runtransaction). | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [DatabaseReference](./database.databasereference.md#databasereference_interface) | A DatabaseReference represents a specific location in your Database and can be used for reading or writing data to that Database location.You can reference the root or child location in your Database by calling ref() or ref("child/path").Writing is done with the set() method and reading can be done with the on*() method. See [https://firebase.google.com/docs/database/web/read-and-write](https://firebase.google.com/docs/database/web/read-and-write) | +| [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An options objects that can be used to customize a listener. | +| [Query](./database.query.md#query_interface) | A Query sorts and filters the data at a Database location so only a subset of the child data is included. This can be used to order a collection of data by some attribute (for example, height of dinosaurs) as well as to restrict a large list of items (for example, chat messages) down to a number suitable for synchronizing to the client. Queries are created by chaining together one or more of the filter methods defined here.Just as with a DatabaseReference, you can receive data from a Query by using the on*() methods. You will only receive events and DataSnapshots for the subset of the data that matches your query.See [https://firebase.google.com/docs/database/web/lists-of-data\#sorting\_and\_filtering\_data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) for more information. | +| [ThenableReference](./database.thenablereference.md#thenablereference_interface) | A Promise that can also act as a DatabaseReference when returned by [push()](./database.md#push). The reference is available immediately and the Promise resolves as the write to the backend completes. | +| [TransactionOptions](./database.transactionoptions.md#transactionoptions_interface) | An options object to configure transactions. | + +## Type Aliases + +| Type Alias | Description | +| --- | --- | +| [EventType](./database.md#eventtype) | One of the following strings: "value", "child\_added", "child\_changed", "child\_removed", or "child\_moved." | +| [QueryConstraintType](./database.md#queryconstrainttype) | Describes the different query constraints available in this SDK. | +| [Unsubscribe](./database.md#unsubscribe) | A callback that can invoked to remove a listener. | + +## getDatabase() + +Returns the instance of the Realtime Database SDK that is associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). Initializes a new instance with with default settings if no instance exists or if the existing instance uses a custom database URL. + +Signature: + +```typescript +export declare function getDatabase(app?: FirebaseApp, url?: string): Database; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance that the returned Realtime Database instance is associated with. | +| url | string | The URL of the Realtime Database instance to connect to. If not provided, the SDK connects to the default instance of the Firebase App. | + +Returns: + +[Database](./database.database.md#database_class) + +The `Database` instance of the provided app. + +## connectDatabaseEmulator() + +Modify the provided instance to communicate with the Realtime Database emulator. + +

Note: This method must be called before performing any other operation. + +Signature: + +```typescript +export declare function connectDatabaseEmulator(db: Database, host: string, port: number, options?: { + mockUserToken?: EmulatorMockTokenOptions | string; +}): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| db | [Database](./database.database.md#database_class) | The instance to modify. | +| host | string | The emulator host (ex: localhost) | +| port | number | The emulator port (ex: 8080) | +| options | { mockUserToken?: [EmulatorMockTokenOptions](./util.md#emulatormocktokenoptions) \| string; } | | + +Returns: + +void + +## goOffline() + +Disconnects from the server (all Database operations will be completed offline). + +The client automatically maintains a persistent connection to the Database server, which will remain active indefinitely and reconnect when disconnected. However, the `goOffline()` and `goOnline()` methods may be used to control the client connection in cases where a persistent connection is undesirable. + +While offline, the client will no longer receive data updates from the Database. However, all Database operations performed locally will continue to immediately fire events, allowing your application to continue behaving normally. Additionally, each operation performed locally will automatically be queued and retried upon reconnection to the Database server. + +To reconnect to the Database and begin receiving remote events, see `goOnline()`. + +Signature: + +```typescript +export declare function goOffline(db: Database): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| db | [Database](./database.database.md#database_class) | The instance to disconnect. | + +Returns: + +void + +## goOnline() + +Reconnects to the server and synchronizes the offline Database state with the server state. + +This method should be used after disabling the active connection with `goOffline()`. Once reconnected, the client will transmit the proper data and fire the appropriate events so that your client "catches up" automatically. + +Signature: + +```typescript +export declare function goOnline(db: Database): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| db | [Database](./database.database.md#database_class) | The instance to reconnect. | + +Returns: + +void + +## ref() + +Returns a `Reference` representing the location in the Database corresponding to the provided path. If no path is provided, the `Reference` will point to the root of the Database. + +Signature: + +```typescript +export declare function ref(db: Database, path?: string): DatabaseReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| db | [Database](./database.database.md#database_class) | The database instance to obtain a reference for. | +| path | string | Optional path representing the location the returned Reference will point. If not provided, the returned Reference will point to the root of the Database. | + +Returns: + +[DatabaseReference](./database.databasereference.md#databasereference_interface) + +If a path is provided, a `Reference` pointing to the provided path. Otherwise, a `Reference` pointing to the root of the Database. + +## refFromURL() + +Returns a `Reference` representing the location in the Database corresponding to the provided Firebase URL. + +An exception is thrown if the URL is not a valid Firebase Database URL or it has a different domain than the current `Database` instance. + +Note that all query parameters (`orderBy`, `limitToLast`, etc.) are ignored and are not applied to the returned `Reference`. + +Signature: + +```typescript +export declare function refFromURL(db: Database, url: string): DatabaseReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| db | [Database](./database.database.md#database_class) | The database instance to obtain a reference for. | +| url | string | The Firebase URL at which the returned Reference will point. | + +Returns: + +[DatabaseReference](./database.databasereference.md#databasereference_interface) + +A `Reference` pointing to the provided Firebase URL. + +## forceLongPolling() + +Force the use of longPolling instead of websockets. This will be ignored if websocket protocol is used in databaseURL. + +Signature: + +```typescript +export declare function forceLongPolling(): void; +``` +Returns: + +void + +## forceWebSockets() + +Force the use of websockets instead of longPolling. + +Signature: + +```typescript +export declare function forceWebSockets(): void; +``` +Returns: + +void + +## orderByKey() + +Creates a new `QueryConstraint` that orders by the key. + +Sorts the results of a query by their (ascending) key values. + +You can read more about `orderByKey()` in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). + +Signature: + +```typescript +export declare function orderByKey(): QueryConstraint; +``` +Returns: + +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) + +## orderByPriority() + +Creates a new `QueryConstraint` that orders by priority. + +Applications need not use priority but can order collections by ordinary properties (see [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data) for alternatives to priority. + +Signature: + +```typescript +export declare function orderByPriority(): QueryConstraint; +``` +Returns: + +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) + +## orderByValue() + +Creates a new `QueryConstraint` that orders by value. + +If the children of a query are all scalar values (string, number, or boolean), you can order the results by their (ascending) values. + +You can read more about `orderByValue()` in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). + +Signature: + +```typescript +export declare function orderByValue(): QueryConstraint; +``` +Returns: + +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) + +## serverTimestamp() + +Returns a placeholder value for auto-populating the current timestamp (time since the Unix epoch, in milliseconds) as determined by the Firebase servers. + +Signature: + +```typescript +export declare function serverTimestamp(): object; +``` +Returns: + +object + +## increment() + +Returns a placeholder value that can be used to atomically increment the current database value by the provided delta. + +Signature: + +```typescript +export declare function increment(delta: number): object; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| delta | number | the amount to modify the current value atomically. | + +Returns: + +object + +A placeholder value for modifying data atomically server-side. + +## enableLogging() + +Logs debugging information to the console. + +Signature: + +```typescript +export declare function enableLogging(enabled: boolean, persistent?: boolean): any; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| enabled | boolean | Enables logging if true, disables logging if false. | +| persistent | boolean | Remembers the logging state between page refreshes if true. | + +Returns: + +any + +## limitToFirst() + +Creates a new `QueryConstraint` that if limited to the first specific number of children. + +The `limitToFirst()` method is used to set a maximum number of children to be synced for a given callback. If we set a limit of 100, we will initially only receive up to 100 `child_added` events. If we have fewer than 100 messages stored in our Database, a `child_added` event will fire for each message. However, if we have over 100 messages, we will only receive a `child_added` event for the first 100 ordered messages. As items change, we will receive `child_removed` events for each item that drops out of the active list so that the total number stays at 100. + +You can read more about `limitToFirst()` in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). + +Signature: + +```typescript +export declare function limitToFirst(limit: number): QueryConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| limit | number | The maximum number of nodes to include in this query. | + +Returns: + +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) + +## limitToLast() + +Creates a new `QueryConstraint` that is limited to return only the last specified number of children. + +The `limitToLast()` method is used to set a maximum number of children to be synced for a given callback. If we set a limit of 100, we will initially only receive up to 100 `child_added` events. If we have fewer than 100 messages stored in our Database, a `child_added` event will fire for each message. However, if we have over 100 messages, we will only receive a `child_added` event for the last 100 ordered messages. As items change, we will receive `child_removed` events for each item that drops out of the active list so that the total number stays at 100. + +You can read more about `limitToLast()` in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). + +Signature: + +```typescript +export declare function limitToLast(limit: number): QueryConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| limit | number | The maximum number of nodes to include in this query. | + +Returns: + +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) + +## enableLogging() + +Logs debugging information to the console. + +Signature: + +```typescript +export declare function enableLogging(logger: (message: string) => unknown): any; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| logger | (message: string) => unknown | A custom logger function to control how things get logged. | + +Returns: + +any + +## child() + +Gets a `Reference` for the location at the specified relative path. + +The relative path can either be a simple child name (for example, "ada") or a deeper slash-separated path (for example, "ada/name/first"). + +Signature: + +```typescript +export declare function child(parent: DatabaseReference, path: string): DatabaseReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| parent | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The parent location. | +| path | string | A relative path from this location to the desired child location. | + +Returns: + +[DatabaseReference](./database.databasereference.md#databasereference_interface) + +The specified child location. + +## push() + +Generates a new child location using a unique key and returns its `Reference`. + +This is the most common pattern for adding data to a collection of items. + +If you provide a value to `push()`, the value is written to the generated location. If you don't pass a value, nothing is written to the database and the child remains empty (but you can use the `Reference` elsewhere). + +The unique keys generated by `push()` are ordered by the current time, so the resulting list of items is chronologically sorted. The keys are also designed to be unguessable (they contain 72 random bits of entropy). + +See [Append to a list of data](https://firebase.google.com/docs/database/web/lists-of-data#append_to_a_list_of_data). See [The 2^120 Ways to Ensure Unique Identifiers](https://firebase.googleblog.com/2015/02/the-2120-ways-to-ensure-unique_68.html). + +Signature: + +```typescript +export declare function push(parent: DatabaseReference, value?: unknown): ThenableReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| parent | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The parent location. | +| value | unknown | Optional value to be written at the generated location. | + +Returns: + +[ThenableReference](./database.thenablereference.md#thenablereference_interface) + +Combined `Promise` and `Reference`; resolves when write is complete, but can be used immediately as the `Reference` to the child location. + +## orderByChild() + +Creates a new `QueryConstraint` that orders by the specified child key. + +Queries can only order by one key at a time. Calling `orderByChild()` multiple times on the same query is an error. + +Firebase queries allow you to order your data by any child key on the fly. However, if you know in advance what your indexes will be, you can define them via the .indexOn rule in your Security Rules for better performance. See the[https://firebase.google.com/docs/database/security/indexing-data](https://firebase.google.com/docs/database/security/indexing-data) rule for more information. + +You can read more about `orderByChild()` in [Sort data](https://firebase.google.com/docs/database/web/lists-of-data#sort_data). + +Signature: + +```typescript +export declare function orderByChild(path: string): QueryConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| path | string | The path to order by. | + +Returns: + +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) + +## get() + +Gets the most up-to-date result for this query. + +Signature: + +```typescript +export declare function get(query: Query): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | + +Returns: + +Promise<[DataSnapshot](./database.datasnapshot.md#datasnapshot_class)> + +A `Promise` which resolves to the resulting DataSnapshot if a value is available, or rejects if the client is unable to return a value (e.g., if the server is unreachable and there is nothing cached). + +## off() + +Detaches a callback previously attached with the corresponding `on*()` (`onValue`, `onChildAdded`) listener. Note: This is not the recommended way to remove a listener. Instead, please use the returned callback function from the respective `on*` callbacks. + +Detach a callback previously attached with `on*()`. Calling `off()` on a parent listener will not automatically remove listeners registered on child nodes, `off()` must also be called on any child listeners to remove the callback. + +If a callback is not specified, all callbacks for the specified eventType will be removed. Similarly, if no eventType is specified, all callbacks for the `Reference` will be removed. + +Individual listeners can also be removed by invoking their unsubscribe callbacks. + +Signature: + +```typescript +export declare function off(query: Query, eventType?: EventType, callback?: (snapshot: DataSnapshot, previousChildName?: string | null) => unknown): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query that the listener was registered with. | +| eventType | [EventType](./database.md#eventtype) | One of the following strings: "value", "child\_added", "child\_changed", "child\_removed", or "child\_moved." If omitted, all callbacks for the Reference will be removed. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName?: string \| null) => unknown | The callback function that was passed to on() or undefined to remove all callbacks. | + +Returns: + +void + +## onChildAdded() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onChildAdded` event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The `DataSnapshot` passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. + +Signature: + +```typescript +export declare function onChildAdded(query: Query, callback: (snapshot: DataSnapshot, previousChildName?: string | null) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName?: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | +| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onChildAdded() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onChildAdded` event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The `DataSnapshot` passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. + +Signature: + +```typescript +export declare function onChildAdded(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, options: ListenOptions): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | +| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onChildAdded() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onChildAdded` event will be triggered once for each initial child at this location, and it will be triggered again every time a new child is added. The `DataSnapshot` passed into the callback will reflect the data for the relevant child. For ordering purposes, it is passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. + +Signature: + +```typescript +export declare function onChildAdded(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | +| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | +| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onChildChanged() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onChildChanged` event will be triggered when the data stored in a child (or any of its descendants) changes. Note that a single `child_changed` event may represent multiple changes to the child. The `DataSnapshot` passed to the callback will contain the new child contents. For ordering purposes, the callback is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. + +Signature: + +```typescript +export declare function onChildChanged(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | +| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onChildChanged() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onChildChanged` event will be triggered when the data stored in a child (or any of its descendants) changes. Note that a single `child_changed` event may represent multiple changes to the child. The `DataSnapshot` passed to the callback will contain the new child contents. For ordering purposes, the callback is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. + +Signature: + +```typescript +export declare function onChildChanged(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, options: ListenOptions): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | +| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onChildChanged() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onChildChanged` event will be triggered when the data stored in a child (or any of its descendants) changes. Note that a single `child_changed` event may represent multiple changes to the child. The `DataSnapshot` passed to the callback will contain the new child contents. For ordering purposes, the callback is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. + +Signature: + +```typescript +export declare function onChildChanged(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | +| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | +| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onChildMoved() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onChildMoved` event will be triggered when a child's sort order changes such that its position relative to its siblings changes. The `DataSnapshot` passed to the callback will be for the data of the child that has moved. It is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. + +Signature: + +```typescript +export declare function onChildMoved(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | +| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onChildMoved() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onChildMoved` event will be triggered when a child's sort order changes such that its position relative to its siblings changes. The `DataSnapshot` passed to the callback will be for the data of the child that has moved. It is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. + +Signature: + +```typescript +export declare function onChildMoved(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, options: ListenOptions): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | +| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onChildMoved() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onChildMoved` event will be triggered when a child's sort order changes such that its position relative to its siblings changes. The `DataSnapshot` passed to the callback will be for the data of the child that has moved. It is also passed a second argument which is a string containing the key of the previous sibling child by sort order, or `null` if it is the first child. + +Signature: + +```typescript +export declare function onChildMoved(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class), previousChildName: string \| null) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | +| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | +| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onChildRemoved() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onChildRemoved` event will be triggered once every time a child is removed. The `DataSnapshot` passed into the callback will be the old data for the child that was removed. A child will get removed when either: + +- a client explicitly calls `remove()` on that child or one of its ancestors - a client calls `set(null)` on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) + +Signature: + +```typescript +export declare function onChildRemoved(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | +| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onChildRemoved() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onChildRemoved` event will be triggered once every time a child is removed. The `DataSnapshot` passed into the callback will be the old data for the child that was removed. A child will get removed when either: + +- a client explicitly calls `remove()` on that child or one of its ancestors - a client calls `set(null)` on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) + +Signature: + +```typescript +export declare function onChildRemoved(query: Query, callback: (snapshot: DataSnapshot) => unknown, options: ListenOptions): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | +| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onChildRemoved() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onChildRemoved` event will be triggered once every time a child is removed. The `DataSnapshot` passed into the callback will be the old data for the child that was removed. A child will get removed when either: + +- a client explicitly calls `remove()` on that child or one of its ancestors - a client calls `set(null)` on that child or one of its ancestors - that child has all of its children removed - there is a query in effect which now filters out the child (because it's sort order changed or the max limit was hit) + +Signature: + +```typescript +export declare function onChildRemoved(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot and a string containing the key of the previous child, by sort order, or null if it is the first child. | +| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | +| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onValue() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onValue` event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The `DataSnapshot` passed to the callback will be for the location at which `on()` was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty `DataSnapshot` (`val()` will return `null`). + +Signature: + +```typescript +export declare function onValue(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot. | +| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onValue() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onValue` event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The `DataSnapshot` passed to the callback will be for the location at which `on()` was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty `DataSnapshot` (`val()` will return `null`). + +Signature: + +```typescript +export declare function onValue(query: Query, callback: (snapshot: DataSnapshot) => unknown, options: ListenOptions): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot. | +| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## onValue() + +Listens for data changes at a particular location. + +This is the primary way to read data from a Database. Your callback will be triggered for the initial data and again whenever the data changes. Invoke the returned unsubscribe callback to stop receiving updates. See [Retrieve Data on the Web](https://firebase.google.com/docs/database/web/retrieve-data) for more details. + +An `onValue` event will trigger once with the initial data stored at this location, and then trigger again each time the data changes. The `DataSnapshot` passed to the callback will be for the location at which `on()` was called. It won't trigger until the entire contents has been synchronized. If the location has no data, it will be triggered with an empty `DataSnapshot` (`val()` will return `null`). + +Signature: + +```typescript +export declare function onValue(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The query to run. | +| callback | (snapshot: [DataSnapshot](./database.datasnapshot.md#datasnapshot_class)) => unknown | A callback that fires when the specified event occurs. The callback will be passed a DataSnapshot. | +| cancelCallback | (error: Error) => unknown | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an Error object indicating why the failure occurred. | +| options | [ListenOptions](./database.listenoptions.md#listenoptions_interface) | An object that can be used to configure onlyOnce, which then removes the listener after its first invocation. | + +Returns: + +[Unsubscribe](./database.md#unsubscribe) + +A function that can be invoked to remove the listener. + +## query() + +Creates a new immutable instance of `Query` that is extended to also include additional query constraints. + +Signature: + +```typescript +export declare function query(query: Query, ...queryConstraints: QueryConstraint[]): Query; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./database.query.md#query_interface) | The Query instance to use as a base for the new constraints. | +| queryConstraints | [QueryConstraint](./database.queryconstraint.md#queryconstraint_class)\[\] | The list of QueryConstraints to apply. | + +Returns: + +[Query](./database.query.md#query_interface) + +## Exceptions + +if any of the provided query constraints cannot be combined with the existing or new constraints. + +## onDisconnect() + +Returns an `OnDisconnect` object - see [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information on how to use it. + +Signature: + +```typescript +export declare function onDisconnect(ref: DatabaseReference): OnDisconnect; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The reference to add OnDisconnect triggers for. | + +Returns: + +[OnDisconnect](./database.ondisconnect.md#ondisconnect_class) + +## remove() + +Removes the data at this Database location. + +Any data at child locations will also be deleted. + +The effect of the remove will be visible immediately and the corresponding event 'value' will be triggered. Synchronization of the remove to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the onComplete callback will be called asynchronously after synchronization has finished. + +Signature: + +```typescript +export declare function remove(ref: DatabaseReference): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location to remove. | + +Returns: + +Promise<void> + +Resolves when remove on server is complete. + +## runTransaction() + +Atomically modifies the data at this location. + +Atomically modify the data at this location. Unlike a normal `set()`, which just overwrites the data regardless of its previous value, `runTransaction()` is used to modify the existing value to a new value, ensuring there are no conflicts with other clients writing to the same location at the same time. + +To accomplish this, you pass `runTransaction()` an update function which is used to transform the current value into a new value. If another client writes to the location before your new value is successfully written, your update function will be called again with the new current value, and the write will be retried. This will happen repeatedly until your write succeeds without conflict or you abort the transaction by not returning a value from your update function. + +Note: Modifying data with `set()` will cancel any pending transactions at that location, so extreme care should be taken if mixing `set()` and `runTransaction()` to update the same data. + +Note: When using transactions with Security and Firebase Rules in place, be aware that a client needs `.read` access in addition to `.write` access in order to perform a transaction. This is because the client-side nature of transactions requires the client to read the data in order to transactionally update it. + +Signature: + +```typescript +export declare function runTransaction(ref: DatabaseReference, transactionUpdate: (currentData: any) => unknown, options?: TransactionOptions): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location to atomically modify. | +| transactionUpdate | (currentData: any) => unknown | A developer-supplied function which will be passed the current data stored at this location (as a JavaScript object). The function should return the new value it would like written (as a JavaScript object). If undefined is returned (i.e. you return with no arguments) the transaction will be aborted and the data at this location will not be modified. | +| options | [TransactionOptions](./database.transactionoptions.md#transactionoptions_interface) | An options object to configure transactions. | + +Returns: + +Promise<[TransactionResult](./database.transactionresult.md#transactionresult_class)> + +A `Promise` that can optionally be used instead of the `onComplete` callback to handle success and failure. + +## set() + +Writes data to this Database location. + +This will overwrite any data at this location and all child locations. + +The effect of the write will be visible immediately, and the corresponding events ("value", "child\_added", etc.) will be triggered. Synchronization of the data to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the `onComplete` callback will be called asynchronously after synchronization has finished. + +Passing `null` for the new value is equivalent to calling `remove()`; namely, all data at this location and all child locations will be deleted. + +`set()` will remove any priority stored at this location, so if priority is meant to be preserved, you need to use `setWithPriority()` instead. + +Note that modifying data with `set()` will cancel any pending transactions at that location, so extreme care should be taken if mixing `set()` and `transaction()` to modify the same data. + +A single `set()` will generate a single "value" event at the location where the `set()` was performed. + +Signature: + +```typescript +export declare function set(ref: DatabaseReference, value: unknown): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location to write to. | +| value | unknown | The value to be written (string, number, boolean, object, array, or null). | + +Returns: + +Promise<void> + +Resolves when write to server is complete. + +## setPriority() + +Sets a priority for the data at this Database location. + +Applications need not use priority but can order collections by ordinary properties (see [Sorting and filtering data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) ). + +Signature: + +```typescript +export declare function setPriority(ref: DatabaseReference, priority: string | number | null): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location to write to. | +| priority | string \| number \| null | The priority to be written (string, number, or null). | + +Returns: + +Promise<void> + +Resolves when write to server is complete. + +## setWithPriority() + +Writes data the Database location. Like `set()` but also specifies the priority for that data. + +Applications need not use priority but can order collections by ordinary properties (see [Sorting and filtering data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) ). + +Signature: + +```typescript +export declare function setWithPriority(ref: DatabaseReference, value: unknown, priority: string | number | null): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location to write to. | +| value | unknown | The value to be written (string, number, boolean, object, array, or null). | +| priority | string \| number \| null | The priority to be written (string, number, or null). | + +Returns: + +Promise<void> + +Resolves when write to server is complete. + +## update() + +Writes multiple values to the Database at once. + +The `values` argument contains multiple property-value pairs that will be written to the Database together. Each child property can either be a simple property (for example, "name") or a relative path (for example, "name/first") from the current location to the data to update. + +As opposed to the `set()` method, `update()` can be use to selectively update only the referenced properties at the current location (instead of replacing all the child properties at the current location). + +The effect of the write will be visible immediately, and the corresponding events ('value', 'child\_added', etc.) will be triggered. Synchronization of the data to the Firebase servers will also be started, and the returned Promise will resolve when complete. If provided, the `onComplete` callback will be called asynchronously after synchronization has finished. + +A single `update()` will generate a single "value" event at the location where the `update()` was performed, regardless of how many children were modified. + +Note that modifying data with `update()` will cancel any pending transactions at that location, so extreme care should be taken if mixing `update()` and `transaction()` to modify the same data. + +Passing `null` to `update()` will remove the data at this location. + +See [Introducing multi-location updates and more](https://firebase.googleblog.com/2015/09/introducing-multi-location-updates-and_86.html). + +Signature: + +```typescript +export declare function update(ref: DatabaseReference, values: object): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The location to write to. | +| values | object | Object containing multiple values. | + +Returns: + +Promise<void> + +Resolves when update on server is complete. + +## endAt() + +Creates a `QueryConstraint` with the specified ending point. + +Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. + +The ending point is inclusive, so children with exactly the specified value will be included in the query. The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have a key name less than or equal to the specified key. + +You can read more about `endAt()` in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). + +Signature: + +```typescript +export declare function endAt(value: number | string | boolean | null, key?: string): QueryConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| value | number \| string \| boolean \| null | The value to end at. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | +| key | string | The child key to end at, among the children with the previously specified priority. This argument is only allowed if ordering by child, value, or priority. | + +Returns: + +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) + +## endBefore() + +Creates a `QueryConstraint` with the specified ending point (exclusive). + +Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. + +The ending point is exclusive. If only a value is provided, children with a value less than the specified value will be included in the query. If a key is specified, then children must have a value less than or equal to the specified value and a key name less than the specified key. + +Signature: + +```typescript +export declare function endBefore(value: number | string | boolean | null, key?: string): QueryConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| value | number \| string \| boolean \| null | The value to end before. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | +| key | string | The child key to end before, among the children with the previously specified priority. This argument is only allowed if ordering by child, value, or priority. | + +Returns: + +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) + +## equalTo() + +Creates a `QueryConstraint` that includes children that match the specified value. + +Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. + +The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have exactly the specified key as their key name. This can be used to filter result sets with many matches for the same value. + +You can read more about `equalTo()` in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). + +Signature: + +```typescript +export declare function equalTo(value: number | string | boolean | null, key?: string): QueryConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| value | number \| string \| boolean \| null | The value to match for. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | +| key | string | The child key to start at, among the children with the previously specified priority. This argument is only allowed if ordering by child, value, or priority. | + +Returns: + +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) + +## startAfter() + +Creates a `QueryConstraint` with the specified starting point (exclusive). + +Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. + +The starting point is exclusive. If only a value is provided, children with a value greater than the specified value will be included in the query. If a key is specified, then children must have a value greater than or equal to the specified value and a a key name greater than the specified key. + +Signature: + +```typescript +export declare function startAfter(value: number | string | boolean | null, key?: string): QueryConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| value | number \| string \| boolean \| null | The value to start after. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | +| key | string | The child key to start after. This argument is only allowed if ordering by child, value, or priority. | + +Returns: + +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) + +## startAt() + +Creates a `QueryConstraint` with the specified starting point. + +Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` allows you to choose arbitrary starting and ending points for your queries. + +The starting point is inclusive, so children with exactly the specified value will be included in the query. The optional key argument can be used to further limit the range of the query. If it is specified, then children that have exactly the specified value must also have a key name greater than or equal to the specified key. + +You can read more about `startAt()` in [Filtering data](https://firebase.google.com/docs/database/web/lists-of-data#filtering_data). + +Signature: + +```typescript +export declare function startAt(value?: number | string | boolean | null, key?: string): QueryConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| value | number \| string \| boolean \| null | The value to start at. The argument type depends on which orderBy*() function was used in this query. Specify a value that matches the orderBy*() type. When used in combination with orderByKey(), the value must be a string. | +| key | string | The child key to start at. This argument is only allowed if ordering by child, value, or priority. | + +Returns: + +[QueryConstraint](./database.queryconstraint.md#queryconstraint_class) + +## EventType + +One of the following strings: "value", "child\_added", "child\_changed", "child\_removed", or "child\_moved." + +Signature: + +```typescript +export declare type EventType = 'value' | 'child_added' | 'child_changed' | 'child_moved' | 'child_removed'; +``` + +## QueryConstraintType + +Describes the different query constraints available in this SDK. + +Signature: + +```typescript +export declare type QueryConstraintType = 'endAt' | 'endBefore' | 'startAt' | 'startAfter' | 'limitToFirst' | 'limitToLast' | 'orderByChild' | 'orderByKey' | 'orderByPriority' | 'orderByValue' | 'equalTo'; +``` + +## Unsubscribe + +A callback that can invoked to remove a listener. + +Signature: + +```typescript +export declare type Unsubscribe = () => void; +``` diff --git a/docs-devsite/database.ondisconnect.md b/docs-devsite/database.ondisconnect.md new file mode 100644 index 00000000000..b7ed5075365 --- /dev/null +++ b/docs-devsite/database.ondisconnect.md @@ -0,0 +1,143 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# OnDisconnect class +The `onDisconnect` class allows you to write or clear data when your client disconnects from the Database server. These updates occur whether your client disconnects cleanly or not, so you can rely on them to clean up data even if a connection is dropped or a client crashes. + +The `onDisconnect` class is most commonly used to manage presence in applications where it is useful to detect how many clients are connected and when other clients disconnect. See [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information. + +To avoid problems when a connection is dropped before the requests can be transferred to the Database server, these functions should be called before writing any data. + +Note that `onDisconnect` operations are only triggered once. If you want an operation to occur each time a disconnect occurs, you'll need to re-establish the `onDisconnect` operations each time you reconnect. + +Signature: + +```typescript +export declare class OnDisconnect +``` + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [cancel()](./database.ondisconnect.md#ondisconnectcancel) | | Cancels all previously queued onDisconnect() set or update events for this location and all children.If a write has been queued for this location via a set() or update() at a parent location, the write at this location will be canceled, though writes to sibling locations will still occur. | +| [remove()](./database.ondisconnect.md#ondisconnectremove) | | Ensures the data at this location is deleted when the client is disconnected (due to closing the browser, navigating to a new page, or network issues). | +| [set(value)](./database.ondisconnect.md#ondisconnectset) | | Ensures the data at this location is set to the specified value when the client is disconnected (due to closing the browser, navigating to a new page, or network issues).set() is especially useful for implementing "presence" systems, where a value should be changed or cleared when a user disconnects so that they appear "offline" to other users. See [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information.Note that onDisconnect operations are only triggered once. If you want an operation to occur each time a disconnect occurs, you'll need to re-establish the onDisconnect operations each time. | +| [setWithPriority(value, priority)](./database.ondisconnect.md#ondisconnectsetwithpriority) | | Ensures the data at this location is set to the specified value and priority when the client is disconnected (due to closing the browser, navigating to a new page, or network issues). | +| [update(values)](./database.ondisconnect.md#ondisconnectupdate) | | Writes multiple values at this location when the client is disconnected (due to closing the browser, navigating to a new page, or network issues).The values argument contains multiple property-value pairs that will be written to the Database together. Each child property can either be a simple property (for example, "name") or a relative path (for example, "name/first") from the current location to the data to update.As opposed to the set() method, update() can be use to selectively update only the referenced properties at the current location (instead of replacing all the child properties at the current location). | + +## OnDisconnect.cancel() + +Cancels all previously queued `onDisconnect()` set or update events for this location and all children. + +If a write has been queued for this location via a `set()` or `update()` at a parent location, the write at this location will be canceled, though writes to sibling locations will still occur. + +Signature: + +```typescript +cancel(): Promise; +``` +Returns: + +Promise<void> + +Resolves when synchronization to the server is complete. + +## OnDisconnect.remove() + +Ensures the data at this location is deleted when the client is disconnected (due to closing the browser, navigating to a new page, or network issues). + +Signature: + +```typescript +remove(): Promise; +``` +Returns: + +Promise<void> + +Resolves when synchronization to the server is complete. + +## OnDisconnect.set() + +Ensures the data at this location is set to the specified value when the client is disconnected (due to closing the browser, navigating to a new page, or network issues). + +`set()` is especially useful for implementing "presence" systems, where a value should be changed or cleared when a user disconnects so that they appear "offline" to other users. See [Enabling Offline Capabilities in JavaScript](https://firebase.google.com/docs/database/web/offline-capabilities) for more information. + +Note that `onDisconnect` operations are only triggered once. If you want an operation to occur each time a disconnect occurs, you'll need to re-establish the `onDisconnect` operations each time. + +Signature: + +```typescript +set(value: unknown): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| value | unknown | The value to be written to this location on disconnect (can be an object, array, string, number, boolean, or null). | + +Returns: + +Promise<void> + +Resolves when synchronization to the Database is complete. + +## OnDisconnect.setWithPriority() + +Ensures the data at this location is set to the specified value and priority when the client is disconnected (due to closing the browser, navigating to a new page, or network issues). + +Signature: + +```typescript +setWithPriority(value: unknown, priority: number | string | null): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| value | unknown | The value to be written to this location on disconnect (can be an object, array, string, number, boolean, or null). | +| priority | number \| string \| null | The priority to be written (string, number, or null). | + +Returns: + +Promise<void> + +Resolves when synchronization to the Database is complete. + +## OnDisconnect.update() + +Writes multiple values at this location when the client is disconnected (due to closing the browser, navigating to a new page, or network issues). + +The `values` argument contains multiple property-value pairs that will be written to the Database together. Each child property can either be a simple property (for example, "name") or a relative path (for example, "name/first") from the current location to the data to update. + +As opposed to the `set()` method, `update()` can be use to selectively update only the referenced properties at the current location (instead of replacing all the child properties at the current location). + +Signature: + +```typescript +update(values: object): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| values | object | Object containing multiple values. | + +Returns: + +Promise<void> + +Resolves when synchronization to the Database is complete. + diff --git a/docs-devsite/database.query.md b/docs-devsite/database.query.md new file mode 100644 index 00000000000..8ef7b8f8e46 --- /dev/null +++ b/docs-devsite/database.query.md @@ -0,0 +1,108 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Query interface +A `Query` sorts and filters the data at a Database location so only a subset of the child data is included. This can be used to order a collection of data by some attribute (for example, height of dinosaurs) as well as to restrict a large list of items (for example, chat messages) down to a number suitable for synchronizing to the client. Queries are created by chaining together one or more of the filter methods defined here. + +Just as with a `DatabaseReference`, you can receive data from a `Query` by using the `on*()` methods. You will only receive events and `DataSnapshot`s for the subset of the data that matches your query. + +See [https://firebase.google.com/docs/database/web/lists-of-data\#sorting\_and\_filtering\_data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data) for more information. + +Signature: + +```typescript +export declare interface Query +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [ref](./database.query.md#queryref) | [DatabaseReference](./database.databasereference.md#databasereference_interface) | The DatabaseReference for the Query's location. | + +## Methods + +| Method | Description | +| --- | --- | +| [isEqual(other)](./database.query.md#queryisequal) | Returns whether or not the current and provided queries represent the same location, have the same query parameters, and are from the same instance of FirebaseApp.Two DatabaseReference objects are equivalent if they represent the same location and are from the same instance of FirebaseApp.Two Query objects are equivalent if they represent the same location, have the same query parameters, and are from the same instance of FirebaseApp. Equivalent queries share the same sort order, limits, and starting and ending points. | +| [toJSON()](./database.query.md#querytojson) | Returns a JSON-serializable representation of this object. | +| [toString()](./database.query.md#querytostring) | Gets the absolute URL for this location.The toString() method returns a URL that is ready to be put into a browser, curl command, or a refFromURL() call. Since all of those expect the URL to be url-encoded, toString() returns an encoded URL.Append '.json' to the returned URL when typed into a browser to download JSON-formatted data. If the location is secured (that is, not publicly readable), you will get a permission-denied error. | + +## Query.ref + +The `DatabaseReference` for the `Query`'s location. + +Signature: + +```typescript +readonly ref: DatabaseReference; +``` + +## Query.isEqual() + +Returns whether or not the current and provided queries represent the same location, have the same query parameters, and are from the same instance of `FirebaseApp`. + +Two `DatabaseReference` objects are equivalent if they represent the same location and are from the same instance of `FirebaseApp`. + +Two `Query` objects are equivalent if they represent the same location, have the same query parameters, and are from the same instance of `FirebaseApp`. Equivalent queries share the same sort order, limits, and starting and ending points. + +Signature: + +```typescript +isEqual(other: Query | null): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| other | [Query](./database.query.md#query_interface) \| null | The query to compare against. | + +Returns: + +boolean + +Whether or not the current and provided queries are equivalent. + +## Query.toJSON() + +Returns a JSON-serializable representation of this object. + +Signature: + +```typescript +toJSON(): string; +``` +Returns: + +string + +A JSON-serializable representation of this object. + +## Query.toString() + +Gets the absolute URL for this location. + +The `toString()` method returns a URL that is ready to be put into a browser, curl command, or a `refFromURL()` call. Since all of those expect the URL to be url-encoded, `toString()` returns an encoded URL. + +Append '.json' to the returned URL when typed into a browser to download JSON-formatted data. If the location is secured (that is, not publicly readable), you will get a permission-denied error. + +Signature: + +```typescript +toString(): string; +``` +Returns: + +string + +The absolute URL for this location. + diff --git a/docs-devsite/database.queryconstraint.md b/docs-devsite/database.queryconstraint.md new file mode 100644 index 00000000000..fe98c6badf3 --- /dev/null +++ b/docs-devsite/database.queryconstraint.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryConstraint class +A `QueryConstraint` is used to narrow the set of documents returned by a Database query. `QueryConstraint`s are created by invoking [endAt()](./database.md#endat), [endBefore()](./database.md#endbefore), [startAt()](./database.md#startat), [startAfter()](./database.md#startafter), [limitToFirst()](./database.md#limittofirst), [limitToLast()](./database.md#limittolast), [orderByChild()](./database.md#orderbychild), [orderByChild()](./database.md#orderbychild), [orderByKey()](./database.md#orderbykey) , [orderByPriority()](./database.md#orderbypriority) , [orderByValue()](./database.md#orderbyvalue) or [equalTo()](./database.md#equalto) and can then be passed to [query()](./database.md#query) to create a new query instance that also contains this `QueryConstraint`. + +Signature: + +```typescript +export declare abstract class QueryConstraint +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./database.queryconstraint.md#queryconstrainttype) | | [QueryConstraintType](./database.md#queryconstrainttype) | The type of this query constraints | + +## QueryConstraint.type + +The type of this query constraints + +Signature: + +```typescript +abstract readonly type: QueryConstraintType; +``` diff --git a/docs-devsite/database.thenablereference.md b/docs-devsite/database.thenablereference.md new file mode 100644 index 00000000000..b6231d2bd03 --- /dev/null +++ b/docs-devsite/database.thenablereference.md @@ -0,0 +1,21 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ThenableReference interface +A `Promise` that can also act as a `DatabaseReference` when returned by [push()](./database.md#push). The reference is available immediately and the `Promise` resolves as the write to the backend completes. + +Signature: + +```typescript +export declare interface ThenableReference extends DatabaseReference, Pick, 'then' | 'catch'> +``` +Extends: [DatabaseReference](./database.databasereference.md#databasereference_interface), Pick<Promise<[DatabaseReference](./database.databasereference.md#databasereference_interface)>, 'then' \| 'catch'> + diff --git a/docs-devsite/database.transactionoptions.md b/docs-devsite/database.transactionoptions.md new file mode 100644 index 00000000000..0dee85c3a99 --- /dev/null +++ b/docs-devsite/database.transactionoptions.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# TransactionOptions interface +An options object to configure transactions. + +Signature: + +```typescript +export declare interface TransactionOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [applyLocally](./database.transactionoptions.md#transactionoptionsapplylocally) | boolean | By default, events are raised each time the transaction update function runs. So if it is run multiple times, you may see intermediate states. You can set this to false to suppress these intermediate states and instead wait until the transaction has completed before events are raised. | + +## TransactionOptions.applyLocally + +By default, events are raised each time the transaction update function runs. So if it is run multiple times, you may see intermediate states. You can set this to false to suppress these intermediate states and instead wait until the transaction has completed before events are raised. + +Signature: + +```typescript +readonly applyLocally?: boolean; +``` diff --git a/docs-devsite/database.transactionresult.md b/docs-devsite/database.transactionresult.md new file mode 100644 index 00000000000..aad84fd6a6b --- /dev/null +++ b/docs-devsite/database.transactionresult.md @@ -0,0 +1,66 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# TransactionResult class +A type for the resolve value of [runTransaction()](./database.md#runtransaction). + +Signature: + +```typescript +export declare class TransactionResult +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [committed](./database.transactionresult.md#transactionresultcommitted) | | boolean | Whether the transaction was successfully committed. | +| [snapshot](./database.transactionresult.md#transactionresultsnapshot) | | [DataSnapshot](./database.datasnapshot.md#datasnapshot_class) | The resulting data snapshot. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [toJSON()](./database.transactionresult.md#transactionresulttojson) | | Returns a JSON-serializable representation of this object. | + +## TransactionResult.committed + +Whether the transaction was successfully committed. + +Signature: + +```typescript +readonly committed: boolean; +``` + +## TransactionResult.snapshot + +The resulting data snapshot. + +Signature: + +```typescript +readonly snapshot: DataSnapshot; +``` + +## TransactionResult.toJSON() + +Returns a JSON-serializable representation of this object. + +Signature: + +```typescript +toJSON(): object; +``` +Returns: + +object + diff --git a/docs-devsite/firestore.md b/docs-devsite/firestore.md new file mode 100644 index 00000000000..c8c647cf611 --- /dev/null +++ b/docs-devsite/firestore.md @@ -0,0 +1,19 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# firestore package +Cloud Firestore + +| Entry Point | Description | +| --- | --- | +| [/](./firestore_.md#@firebase/firestore) | | +| [/lite](./firestore_lite.md#@firebase/firestore/lite) | | + diff --git a/docs-devsite/firestore_.aggregatefield.md b/docs-devsite/firestore_.aggregatefield.md new file mode 100644 index 00000000000..0c3957520b3 --- /dev/null +++ b/docs-devsite/firestore_.aggregatefield.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AggregateField class +Represents an aggregation that can be performed by Firestore. + +Signature: + +```typescript +export declare class AggregateField +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_.aggregatefield.md#aggregatefieldtype) | | string | A type string to uniquely identify instances of this class. | + +## AggregateField.type + +A type string to uniquely identify instances of this class. + +Signature: + +```typescript +type: string; +``` diff --git a/docs-devsite/firestore_.aggregatequerysnapshot.md b/docs-devsite/firestore_.aggregatequerysnapshot.md new file mode 100644 index 00000000000..1cf63b5db8b --- /dev/null +++ b/docs-devsite/firestore_.aggregatequerysnapshot.md @@ -0,0 +1,70 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AggregateQuerySnapshot class +The results of executing an aggregation query. + +Signature: + +```typescript +export declare class AggregateQuerySnapshot +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [query](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshotquery) | | [Query](./firestore_.query.md#query_class)<unknown> | The underlying query over which the aggregations recorded in this AggregateQuerySnapshot were performed. | +| [type](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshottype) | | (not declared) | A type string to uniquely identify instances of this class. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [data()](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshotdata) | | Returns the results of the aggregations performed over the underlying query.The keys of the returned object will be the same as those of the AggregateSpec object specified to the aggregation method, and the values will be the corresponding aggregation result. | + +## AggregateQuerySnapshot.query + +The underlying query over which the aggregations recorded in this `AggregateQuerySnapshot` were performed. + +Signature: + +```typescript +readonly query: Query; +``` + +## AggregateQuerySnapshot.type + +A type string to uniquely identify instances of this class. + +Signature: + +```typescript +readonly type = "AggregateQuerySnapshot"; +``` + +## AggregateQuerySnapshot.data() + +Returns the results of the aggregations performed over the underlying query. + +The keys of the returned object will be the same as those of the `AggregateSpec` object specified to the aggregation method, and the values will be the corresponding aggregation result. + +Signature: + +```typescript +data(): AggregateSpecData; +``` +Returns: + +[AggregateSpecData](./firestore_.md#aggregatespecdata)<T> + +The results of the aggregations performed over the underlying query. + diff --git a/docs-devsite/firestore_.aggregatespec.md b/docs-devsite/firestore_.aggregatespec.md new file mode 100644 index 00000000000..be06b6941f3 --- /dev/null +++ b/docs-devsite/firestore_.aggregatespec.md @@ -0,0 +1,19 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AggregateSpec interface +A type whose property values are all `AggregateField` objects. + +Signature: + +```typescript +export declare interface AggregateSpec +``` diff --git a/docs-devsite/firestore_.bytes.md b/docs-devsite/firestore_.bytes.md new file mode 100644 index 00000000000..411abe327c5 --- /dev/null +++ b/docs-devsite/firestore_.bytes.md @@ -0,0 +1,138 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Bytes class +An immutable object representing an array of bytes. + +Signature: + +```typescript +export declare class Bytes +``` + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [fromBase64String(base64)](./firestore_.bytes.md#bytesfrombase64string) | static | Creates a new Bytes object from the given Base64 string, converting it to bytes. | +| [fromUint8Array(array)](./firestore_.bytes.md#bytesfromuint8array) | static | Creates a new Bytes object from the given Uint8Array. | +| [isEqual(other)](./firestore_.bytes.md#bytesisequal) | | Returns true if this Bytes object is equal to the provided one. | +| [toBase64()](./firestore_.bytes.md#bytestobase64) | | Returns the underlying bytes as a Base64-encoded string. | +| [toString()](./firestore_.bytes.md#bytestostring) | | Returns a string representation of the Bytes object. | +| [toUint8Array()](./firestore_.bytes.md#bytestouint8array) | | Returns the underlying bytes in a new Uint8Array. | + +## Bytes.fromBase64String() + +Creates a new `Bytes` object from the given Base64 string, converting it to bytes. + +Signature: + +```typescript +static fromBase64String(base64: string): Bytes; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| base64 | string | The Base64 string used to create the Bytes object. | + +Returns: + +[Bytes](./firestore_.bytes.md#bytes_class) + +## Bytes.fromUint8Array() + +Creates a new `Bytes` object from the given Uint8Array. + +Signature: + +```typescript +static fromUint8Array(array: Uint8Array): Bytes; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| array | Uint8Array | The Uint8Array used to create the Bytes object. | + +Returns: + +[Bytes](./firestore_.bytes.md#bytes_class) + +## Bytes.isEqual() + +Returns true if this `Bytes` object is equal to the provided one. + +Signature: + +```typescript +isEqual(other: Bytes): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| other | [Bytes](./firestore_.bytes.md#bytes_class) | The Bytes object to compare against. | + +Returns: + +boolean + +true if this `Bytes` object is equal to the provided one. + +## Bytes.toBase64() + +Returns the underlying bytes as a Base64-encoded string. + +Signature: + +```typescript +toBase64(): string; +``` +Returns: + +string + +The Base64-encoded string created from the `Bytes` object. + +## Bytes.toString() + +Returns a string representation of the `Bytes` object. + +Signature: + +```typescript +toString(): string; +``` +Returns: + +string + +A string representation of the `Bytes` object. + +## Bytes.toUint8Array() + +Returns the underlying bytes in a new `Uint8Array`. + +Signature: + +```typescript +toUint8Array(): Uint8Array; +``` +Returns: + +Uint8Array + +The Uint8Array created from the `Bytes` object. + diff --git a/docs-devsite/firestore_.collectionreference.md b/docs-devsite/firestore_.collectionreference.md new file mode 100644 index 00000000000..56c81c6b245 --- /dev/null +++ b/docs-devsite/firestore_.collectionreference.md @@ -0,0 +1,121 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# CollectionReference class +A `CollectionReference` object can be used for adding documents, getting document references, and querying for documents (using [query()](./firestore_.md#query)). + +Signature: + +```typescript +export declare class CollectionReference extends Query +``` +Extends: [Query](./firestore_.query.md#query_class)<T> + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [id](./firestore_.collectionreference.md#collectionreferenceid) | | string | The collection's identifier. | +| [parent](./firestore_.collectionreference.md#collectionreferenceparent) | | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> \| null | A reference to the containing DocumentReference if this is a subcollection. If this isn't a subcollection, the reference is null. | +| [path](./firestore_.collectionreference.md#collectionreferencepath) | | string | A string representing the path of the referenced collection (relative to the root of the database). | +| [type](./firestore_.collectionreference.md#collectionreferencetype) | | (not declared) | The type of this Firestore reference. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [withConverter(converter)](./firestore_.collectionreference.md#collectionreferencewithconverter) | | Applies a custom data converter to this CollectionReference, allowing you to use your own custom model objects with Firestore. When you call [addDoc()](./firestore_.md#adddoc) with the returned CollectionReference instance, the provided converter will convert between Firestore data and your custom type U. | +| [withConverter(converter)](./firestore_.collectionreference.md#collectionreferencewithconverter) | | Removes the current converter. | + +## CollectionReference.id + +The collection's identifier. + +Signature: + +```typescript +get id(): string; +``` + +## CollectionReference.parent + +A reference to the containing `DocumentReference` if this is a subcollection. If this isn't a subcollection, the reference is null. + +Signature: + +```typescript +get parent(): DocumentReference | null; +``` + +## CollectionReference.path + +A string representing the path of the referenced collection (relative to the root of the database). + +Signature: + +```typescript +get path(): string; +``` + +## CollectionReference.type + +The type of this Firestore reference. + +Signature: + +```typescript +readonly type = "collection"; +``` + +## CollectionReference.withConverter() + +Applies a custom data converter to this `CollectionReference`, allowing you to use your own custom model objects with Firestore. When you call [addDoc()](./firestore_.md#adddoc) with the returned `CollectionReference` instance, the provided converter will convert between Firestore data and your custom type `U`. + +Signature: + +```typescript +withConverter(converter: FirestoreDataConverter): CollectionReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| converter | [FirestoreDataConverter](./firestore_.firestoredataconverter.md#firestoredataconverter_interface)<U> | Converts objects to and from Firestore. | + +Returns: + +[CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<U> + +A `CollectionReference` that uses the provided converter. + +## CollectionReference.withConverter() + +Removes the current converter. + +Signature: + +```typescript +withConverter(converter: null): CollectionReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| converter | null | null removes the current converter. | + +Returns: + +[CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> + +A `CollectionReference` that does not use a converter. + diff --git a/docs-devsite/firestore_.documentchange.md b/docs-devsite/firestore_.documentchange.md new file mode 100644 index 00000000000..afef795956d --- /dev/null +++ b/docs-devsite/firestore_.documentchange.md @@ -0,0 +1,68 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# DocumentChange interface +A `DocumentChange` represents a change to the documents matching a query. It contains the document affected and the type of change that occurred. + +Signature: + +```typescript +export declare interface DocumentChange +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [doc](./firestore_.documentchange.md#documentchangedoc) | [QueryDocumentSnapshot](./firestore_.querydocumentsnapshot.md#querydocumentsnapshot_class)<T> | The document affected by this change. | +| [newIndex](./firestore_.documentchange.md#documentchangenewindex) | number | The index of the changed document in the result set immediately after this DocumentChange (i.e. supposing that all prior DocumentChange objects and the current DocumentChange object have been applied). Is -1 for 'removed' events. | +| [oldIndex](./firestore_.documentchange.md#documentchangeoldindex) | number | The index of the changed document in the result set immediately prior to this DocumentChange (i.e. supposing that all prior DocumentChange objects have been applied). Is -1 for 'added' events. | +| [type](./firestore_.documentchange.md#documentchangetype) | [DocumentChangeType](./firestore_.md#documentchangetype) | The type of change ('added', 'modified', or 'removed'). | + +## DocumentChange.doc + +The document affected by this change. + +Signature: + +```typescript +readonly doc: QueryDocumentSnapshot; +``` + +## DocumentChange.newIndex + +The index of the changed document in the result set immediately after this `DocumentChange` (i.e. supposing that all prior `DocumentChange` objects and the current `DocumentChange` object have been applied). Is -1 for 'removed' events. + +Signature: + +```typescript +readonly newIndex: number; +``` + +## DocumentChange.oldIndex + +The index of the changed document in the result set immediately prior to this `DocumentChange` (i.e. supposing that all prior `DocumentChange` objects have been applied). Is `-1` for 'added' events. + +Signature: + +```typescript +readonly oldIndex: number; +``` + +## DocumentChange.type + +The type of change ('added', 'modified', or 'removed'). + +Signature: + +```typescript +readonly type: DocumentChangeType; +``` diff --git a/docs-devsite/firestore_.documentdata.md b/docs-devsite/firestore_.documentdata.md new file mode 100644 index 00000000000..09b5eb64b48 --- /dev/null +++ b/docs-devsite/firestore_.documentdata.md @@ -0,0 +1,19 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# DocumentData interface +Document data (for use with [setDoc()](./firestore_lite.md#setdoc)) consists of fields mapped to values. + +Signature: + +```typescript +export declare interface DocumentData +``` diff --git a/docs-devsite/firestore_.documentreference.md b/docs-devsite/firestore_.documentreference.md new file mode 100644 index 00000000000..16dff93b9c8 --- /dev/null +++ b/docs-devsite/firestore_.documentreference.md @@ -0,0 +1,142 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# DocumentReference class +A `DocumentReference` refers to a document location in a Firestore database and can be used to write, read, or listen to the location. The document at the referenced location may or may not exist. + +Signature: + +```typescript +export declare class DocumentReference +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [converter](./firestore_.documentreference.md#documentreferenceconverter) | | [FirestoreDataConverter](./firestore_.firestoredataconverter.md#firestoredataconverter_interface)<T> \| null | If provided, the FirestoreDataConverter associated with this instance. | +| [firestore](./firestore_.documentreference.md#documentreferencefirestore) | | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance the document is in. This is useful for performing transactions, for example. | +| [id](./firestore_.documentreference.md#documentreferenceid) | | string | The document's identifier within its collection. | +| [parent](./firestore_.documentreference.md#documentreferenceparent) | | [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | The collection this DocumentReference belongs to. | +| [path](./firestore_.documentreference.md#documentreferencepath) | | string | A string representing the path of the referenced document (relative to the root of the database). | +| [type](./firestore_.documentreference.md#documentreferencetype) | | (not declared) | The type of this Firestore reference. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [withConverter(converter)](./firestore_.documentreference.md#documentreferencewithconverter) | | Applies a custom data converter to this DocumentReference, allowing you to use your own custom model objects with Firestore. When you call [setDoc()](./firestore_lite.md#setdoc), [getDoc()](./firestore_lite.md#getdoc), etc. with the returned DocumentReference instance, the provided converter will convert between Firestore data and your custom type U. | +| [withConverter(converter)](./firestore_.documentreference.md#documentreferencewithconverter) | | Removes the current converter. | + +## DocumentReference.converter + +If provided, the `FirestoreDataConverter` associated with this instance. + +Signature: + +```typescript +readonly converter: FirestoreDataConverter | null; +``` + +## DocumentReference.firestore + +The [Firestore](./firestore_.firestore.md#firestore_class) instance the document is in. This is useful for performing transactions, for example. + +Signature: + +```typescript +readonly firestore: Firestore; +``` + +## DocumentReference.id + +The document's identifier within its collection. + +Signature: + +```typescript +get id(): string; +``` + +## DocumentReference.parent + +The collection this `DocumentReference` belongs to. + +Signature: + +```typescript +get parent(): CollectionReference; +``` + +## DocumentReference.path + +A string representing the path of the referenced document (relative to the root of the database). + +Signature: + +```typescript +get path(): string; +``` + +## DocumentReference.type + +The type of this Firestore reference. + +Signature: + +```typescript +readonly type = "document"; +``` + +## DocumentReference.withConverter() + +Applies a custom data converter to this `DocumentReference`, allowing you to use your own custom model objects with Firestore. When you call [setDoc()](./firestore_lite.md#setdoc), [getDoc()](./firestore_lite.md#getdoc), etc. with the returned `DocumentReference` instance, the provided converter will convert between Firestore data and your custom type `U`. + +Signature: + +```typescript +withConverter(converter: FirestoreDataConverter): DocumentReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| converter | [FirestoreDataConverter](./firestore_.firestoredataconverter.md#firestoredataconverter_interface)<U> | Converts objects to and from Firestore. | + +Returns: + +[DocumentReference](./firestore_.documentreference.md#documentreference_class)<U> + +A `DocumentReference` that uses the provided converter. + +## DocumentReference.withConverter() + +Removes the current converter. + +Signature: + +```typescript +withConverter(converter: null): DocumentReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| converter | null | null removes the current converter. | + +Returns: + +[DocumentReference](./firestore_.documentreference.md#documentreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> + +A `DocumentReference` that does not use a converter. + diff --git a/docs-devsite/firestore_.documentsnapshot.md b/docs-devsite/firestore_.documentsnapshot.md new file mode 100644 index 00000000000..3ac2ec7dcb2 --- /dev/null +++ b/docs-devsite/firestore_.documentsnapshot.md @@ -0,0 +1,146 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# DocumentSnapshot class +A `DocumentSnapshot` contains data read from a document in your Firestore database. The data can be extracted with `.data()` or `.get()` to get a specific field. + +For a `DocumentSnapshot` that points to a non-existing document, any data access will return 'undefined'. You can use the `exists()` method to explicitly verify a document's existence. + +Signature: + +```typescript +export declare class DocumentSnapshot +``` + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)()](./firestore_.documentsnapshot.md#documentsnapshotconstructor) | | Constructs a new instance of the DocumentSnapshot class | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [id](./firestore_.documentsnapshot.md#documentsnapshotid) | | string | Property of the DocumentSnapshot that provides the document's ID. | +| [metadata](./firestore_.documentsnapshot.md#documentsnapshotmetadata) | | [SnapshotMetadata](./firestore_.snapshotmetadata.md#snapshotmetadata_class) | Metadata about the DocumentSnapshot, including information about its source and local modifications. | +| [ref](./firestore_.documentsnapshot.md#documentsnapshotref) | | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | The DocumentReference for the document included in the DocumentSnapshot. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [data(options)](./firestore_.documentsnapshot.md#documentsnapshotdata) | | Retrieves all fields in the document as an Object. Returns undefined if the document doesn't exist.By default, serverTimestamp() values that have not yet been set to their final value will be returned as null. You can override this by passing an options object. | +| [exists()](./firestore_.documentsnapshot.md#documentsnapshotexists) | | Returns whether or not the data exists. True if the document exists. | +| [get(fieldPath, options)](./firestore_.documentsnapshot.md#documentsnapshotget) | | Retrieves the field specified by fieldPath. Returns undefined if the document or field doesn't exist.By default, a serverTimestamp() that has not yet been set to its final value will be returned as null. You can override this by passing an options object. | + +## DocumentSnapshot.(constructor) + +Constructs a new instance of the `DocumentSnapshot` class + +Signature: + +```typescript +protected constructor(); +``` + +## DocumentSnapshot.id + +Property of the `DocumentSnapshot` that provides the document's ID. + +Signature: + +```typescript +get id(): string; +``` + +## DocumentSnapshot.metadata + +Metadata about the `DocumentSnapshot`, including information about its source and local modifications. + +Signature: + +```typescript +readonly metadata: SnapshotMetadata; +``` + +## DocumentSnapshot.ref + +The `DocumentReference` for the document included in the `DocumentSnapshot`. + +Signature: + +```typescript +get ref(): DocumentReference; +``` + +## DocumentSnapshot.data() + +Retrieves all fields in the document as an `Object`. Returns `undefined` if the document doesn't exist. + +By default, `serverTimestamp()` values that have not yet been set to their final value will be returned as `null`. You can override this by passing an options object. + +Signature: + +```typescript +data(options?: SnapshotOptions): T | undefined; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| options | [SnapshotOptions](./firestore_.snapshotoptions.md#snapshotoptions_interface) | An options object to configure how data is retrieved from the snapshot (for example the desired behavior for server timestamps that have not yet been set to their final value). | + +Returns: + +T \| undefined + +An `Object` containing all fields in the document or `undefined` if the document doesn't exist. + +## DocumentSnapshot.exists() + +Returns whether or not the data exists. True if the document exists. + +Signature: + +```typescript +exists(): this is QueryDocumentSnapshot; +``` +Returns: + +this is [QueryDocumentSnapshot](./firestore_.querydocumentsnapshot.md#querydocumentsnapshot_class)<T> + +## DocumentSnapshot.get() + +Retrieves the field specified by `fieldPath`. Returns `undefined` if the document or field doesn't exist. + +By default, a `serverTimestamp()` that has not yet been set to its final value will be returned as `null`. You can override this by passing an options object. + +Signature: + +```typescript +get(fieldPath: string | FieldPath, options?: SnapshotOptions): any; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldPath | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The path (for example 'foo' or 'foo.bar') to a specific field. | +| options | [SnapshotOptions](./firestore_.snapshotoptions.md#snapshotoptions_interface) | An options object to configure how the field is retrieved from the snapshot (for example the desired behavior for server timestamps that have not yet been set to their final value). | + +Returns: + +any + +The data at the specified field location or undefined if no such field exists in the document. + diff --git a/docs-devsite/firestore_.fieldpath.md b/docs-devsite/firestore_.fieldpath.md new file mode 100644 index 00000000000..8a9143f02a8 --- /dev/null +++ b/docs-devsite/firestore_.fieldpath.md @@ -0,0 +1,72 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FieldPath class +A `FieldPath` refers to a field in a document. The path may consist of a single field name (referring to a top-level field in the document), or a list of field names (referring to a nested field in the document). + +Create a `FieldPath` by providing field names. If more than one field name is provided, the path will point to a nested field in a document. + +Signature: + +```typescript +export declare class FieldPath +``` + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(fieldNames)](./firestore_.fieldpath.md#fieldpathconstructor) | | Creates a FieldPath from the provided field names. If more than one field name is provided, the path will point to a nested field in a document. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [isEqual(other)](./firestore_.fieldpath.md#fieldpathisequal) | | Returns true if this FieldPath is equal to the provided one. | + +## FieldPath.(constructor) + +Creates a `FieldPath` from the provided field names. If more than one field name is provided, the path will point to a nested field in a document. + +Signature: + +```typescript +constructor(...fieldNames: string[]); +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldNames | string\[\] | A list of field names. | + +## FieldPath.isEqual() + +Returns true if this `FieldPath` is equal to the provided one. + +Signature: + +```typescript +isEqual(other: FieldPath): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| other | [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The FieldPath to compare against. | + +Returns: + +boolean + +true if this `FieldPath` is equal to the provided one. + diff --git a/docs-devsite/firestore_.fieldvalue.md b/docs-devsite/firestore_.fieldvalue.md new file mode 100644 index 00000000000..62c034583d6 --- /dev/null +++ b/docs-devsite/firestore_.fieldvalue.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FieldValue class +Sentinel values that can be used when writing document fields with `set()` or `update()`. + +Signature: + +```typescript +export declare abstract class FieldValue +``` + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [isEqual(other)](./firestore_.fieldvalue.md#fieldvalueisequal) | | Compares FieldValues for equality. | + +## FieldValue.isEqual() + +Compares `FieldValue`s for equality. + +Signature: + +```typescript +abstract isEqual(other: FieldValue): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| other | [FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) | | + +Returns: + +boolean + diff --git a/docs-devsite/firestore_.firestore.md b/docs-devsite/firestore_.firestore.md new file mode 100644 index 00000000000..01267d5b2d3 --- /dev/null +++ b/docs-devsite/firestore_.firestore.md @@ -0,0 +1,68 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Firestore class +The Cloud Firestore service interface. + +Do not call this constructor directly. Instead, use [getFirestore()](./firestore_.md#getfirestore). + +Signature: + +```typescript +export declare class Firestore +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [app](./firestore_.firestore.md#firestoreapp) | | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this Firestore service instance. | +| [type](./firestore_.firestore.md#firestoretype) | | 'firestore-lite' \| 'firestore' | Whether it's a [Firestore](./firestore_.firestore.md#firestore_class) or Firestore Lite instance. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [toJSON()](./firestore_.firestore.md#firestoretojson) | | Returns a JSON-serializable representation of this Firestore instance. | + +## Firestore.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this `Firestore` service instance. + +Signature: + +```typescript +get app(): FirebaseApp; +``` + +## Firestore.type + +Whether it's a [Firestore](./firestore_.firestore.md#firestore_class) or Firestore Lite instance. + +Signature: + +```typescript +type: 'firestore-lite' | 'firestore'; +``` + +## Firestore.toJSON() + +Returns a JSON-serializable representation of this `Firestore` instance. + +Signature: + +```typescript +toJSON(): object; +``` +Returns: + +object + diff --git a/docs-devsite/firestore_.firestoredataconverter.md b/docs-devsite/firestore_.firestoredataconverter.md new file mode 100644 index 00000000000..f7d80ac4a13 --- /dev/null +++ b/docs-devsite/firestore_.firestoredataconverter.md @@ -0,0 +1,134 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FirestoreDataConverter interface +Converter used by `withConverter()` to transform user objects of type `T` into Firestore data. + +Using the converter allows you to specify generic type arguments when storing and retrieving objects from Firestore. + +Signature: + +```typescript +export declare interface FirestoreDataConverter +``` + +## Methods + +| Method | Description | +| --- | --- | +| [fromFirestore(snapshot, options)](./firestore_.firestoredataconverter.md#firestoredataconverterfromfirestore) | Called by the Firestore SDK to convert Firestore data into an object of type T. You can access your data by calling: snapshot.data(options). | +| [toFirestore(modelObject)](./firestore_.firestoredataconverter.md#firestoredataconvertertofirestore) | Called by the Firestore SDK to convert a custom model object of type T into a plain JavaScript object (suitable for writing directly to the Firestore database). To use set() with merge and mergeFields, toFirestore() must be defined with PartialWithFieldValue<T>.The WithFieldValue<T> type extends T to also allow FieldValues such as [deleteField()](./firestore_.md#deletefield) to be used as property values. | +| [toFirestore(modelObject, options)](./firestore_.firestoredataconverter.md#firestoredataconvertertofirestore) | Called by the Firestore SDK to convert a custom model object of type T into a plain JavaScript object (suitable for writing directly to the Firestore database). Used with [setDoc()](./firestore_.md#setdoc), and with merge:true or mergeFields.The PartialWithFieldValue<T> type extends Partial<T> to allow FieldValues such as [arrayUnion()](./firestore_.md#arrayunion) to be used as property values. It also supports nested Partial by allowing nested fields to be omitted. | + +## FirestoreDataConverter.fromFirestore() + +Called by the Firestore SDK to convert Firestore data into an object of type T. You can access your data by calling: `snapshot.data(options)`. + +Signature: + +```typescript +fromFirestore(snapshot: QueryDocumentSnapshot, options?: SnapshotOptions): T; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| snapshot | [QueryDocumentSnapshot](./firestore_.querydocumentsnapshot.md#querydocumentsnapshot_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> | A QueryDocumentSnapshot containing your data and metadata. | +| options | [SnapshotOptions](./firestore_.snapshotoptions.md#snapshotoptions_interface) | The SnapshotOptions from the initial call to data(). | + +Returns: + +T + +## FirestoreDataConverter.toFirestore() + +Called by the Firestore SDK to convert a custom model object of type `T` into a plain JavaScript object (suitable for writing directly to the Firestore database). To use `set()` with `merge` and `mergeFields`, `toFirestore()` must be defined with `PartialWithFieldValue`. + +The `WithFieldValue` type extends `T` to also allow FieldValues such as [deleteField()](./firestore_.md#deletefield) to be used as property values. + +Signature: + +```typescript +toFirestore(modelObject: WithFieldValue): DocumentData; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| modelObject | [WithFieldValue](./firestore_.md#withfieldvalue)<T> | | + +Returns: + +[DocumentData](./firestore_.documentdata.md#documentdata_interface) + +## FirestoreDataConverter.toFirestore() + +Called by the Firestore SDK to convert a custom model object of type `T` into a plain JavaScript object (suitable for writing directly to the Firestore database). Used with [setDoc()](./firestore_.md#setdoc), and with `merge:true` or `mergeFields`. + +The `PartialWithFieldValue` type extends `Partial` to allow FieldValues such as [arrayUnion()](./firestore_.md#arrayunion) to be used as property values. It also supports nested `Partial` by allowing nested fields to be omitted. + +Signature: + +```typescript +toFirestore(modelObject: PartialWithFieldValue, options: SetOptions): DocumentData; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| modelObject | [PartialWithFieldValue](./firestore_.md#partialwithfieldvalue)<T> | | +| options | [SetOptions](./firestore_.md#setoptions) | | + +Returns: + +[DocumentData](./firestore_.documentdata.md#documentdata_interface) + +### Example + + +```typescript +class Post { + constructor(readonly title: string, readonly author: string) {} + + toString(): string { + return this.title + ', by ' + this.author; + } +} + +const postConverter = { + toFirestore(post: WithFieldValue): DocumentData { + return {title: post.title, author: post.author}; + }, + fromFirestore( + snapshot: QueryDocumentSnapshot, + options: SnapshotOptions + ): Post { + const data = snapshot.data(options)!; + return new Post(data.title, data.author); + } +}; + +const postSnap = await firebase.firestore() + .collection('posts') + .withConverter(postConverter) + .doc().get(); +const post = postSnap.data(); +if (post !== undefined) { + post.title; // string + post.toString(); // Should be defined + post.someNonExistentProperty; // TS error +} + +``` + diff --git a/docs-devsite/firestore_.firestoreerror.md b/docs-devsite/firestore_.firestoreerror.md new file mode 100644 index 00000000000..c16cf39541e --- /dev/null +++ b/docs-devsite/firestore_.firestoreerror.md @@ -0,0 +1,58 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FirestoreError class +An error returned by a Firestore operation. + +Signature: + +```typescript +export declare class FirestoreError extends FirebaseError +``` +Extends: [FirebaseError](./util.firebaseerror.md#firebaseerror_class) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [code](./firestore_.firestoreerror.md#firestoreerrorcode) | | [FirestoreErrorCode](./firestore_.md#firestoreerrorcode) | The backend error code associated with this error. | +| [message](./firestore_.firestoreerror.md#firestoreerrormessage) | | string | A custom error description. | +| [stack](./firestore_.firestoreerror.md#firestoreerrorstack) | | string | The stack of the error. | + +## FirestoreError.code + +The backend error code associated with this error. + +Signature: + +```typescript +readonly code: FirestoreErrorCode; +``` + +## FirestoreError.message + +A custom error description. + +Signature: + +```typescript +readonly message: string; +``` + +## FirestoreError.stack + +The stack of the error. + +Signature: + +```typescript +readonly stack?: string; +``` diff --git a/docs-devsite/firestore_.firestoresettings.md b/docs-devsite/firestore_.firestoresettings.md new file mode 100644 index 00000000000..96fe454cb77 --- /dev/null +++ b/docs-devsite/firestore_.firestoresettings.md @@ -0,0 +1,96 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FirestoreSettings interface +Specifies custom configurations for your Cloud Firestore instance. You must set these before invoking any other methods. + +Signature: + +```typescript +export declare interface FirestoreSettings +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [cacheSizeBytes](./firestore_.firestoresettings.md#firestoresettingscachesizebytes) | number | An approximate cache size threshold for the on-disk data. If the cache grows beyond this size, Firestore will start removing data that hasn't been recently used. The size is not a guarantee that the cache will stay below that size, only that if the cache exceeds the given size, cleanup will be attempted.The default value is 40 MB. The threshold must be set to at least 1 MB, and can be set to CACHE_SIZE_UNLIMITED to disable garbage collection. | +| [experimentalAutoDetectLongPolling](./firestore_.firestoresettings.md#firestoresettingsexperimentalautodetectlongpolling) | boolean | Configures the SDK's underlying transport (WebChannel) to automatically detect if long-polling should be used. This is very similar to experimentalForceLongPolling, but only uses long-polling if required.This setting will likely be enabled by default in future releases and cannot be combined with experimentalForceLongPolling. | +| [experimentalForceLongPolling](./firestore_.firestoresettings.md#firestoresettingsexperimentalforcelongpolling) | boolean | Forces the SDK’s underlying network transport (WebChannel) to use long-polling. Each response from the backend will be closed immediately after the backend sends data (by default responses are kept open in case the backend has more data to send). This avoids incompatibility issues with certain proxies, antivirus software, etc. that incorrectly buffer traffic indefinitely. Use of this option will cause some performance degradation though.This setting cannot be used with experimentalAutoDetectLongPolling and may be removed in a future release. If you find yourself using it to work around a specific network reliability issue, please tell us about it in https://github.com/firebase/firebase-js-sdk/issues/1674. | +| [host](./firestore_.firestoresettings.md#firestoresettingshost) | string | The hostname to connect to. | +| [ignoreUndefinedProperties](./firestore_.firestoresettings.md#firestoresettingsignoreundefinedproperties) | boolean | Whether to skip nested properties that are set to undefined during object serialization. If set to true, these properties are skipped and not written to Firestore. If set to false or omitted, the SDK throws an exception when it encounters properties of type undefined. | +| [ssl](./firestore_.firestoresettings.md#firestoresettingsssl) | boolean | Whether to use SSL when connecting. | + +## FirestoreSettings.cacheSizeBytes + +An approximate cache size threshold for the on-disk data. If the cache grows beyond this size, Firestore will start removing data that hasn't been recently used. The size is not a guarantee that the cache will stay below that size, only that if the cache exceeds the given size, cleanup will be attempted. + +The default value is 40 MB. The threshold must be set to at least 1 MB, and can be set to `CACHE_SIZE_UNLIMITED` to disable garbage collection. + +Signature: + +```typescript +cacheSizeBytes?: number; +``` + +## FirestoreSettings.experimentalAutoDetectLongPolling + +Configures the SDK's underlying transport (WebChannel) to automatically detect if long-polling should be used. This is very similar to `experimentalForceLongPolling`, but only uses long-polling if required. + +This setting will likely be enabled by default in future releases and cannot be combined with `experimentalForceLongPolling`. + +Signature: + +```typescript +experimentalAutoDetectLongPolling?: boolean; +``` + +## FirestoreSettings.experimentalForceLongPolling + +Forces the SDK’s underlying network transport (WebChannel) to use long-polling. Each response from the backend will be closed immediately after the backend sends data (by default responses are kept open in case the backend has more data to send). This avoids incompatibility issues with certain proxies, antivirus software, etc. that incorrectly buffer traffic indefinitely. Use of this option will cause some performance degradation though. + +This setting cannot be used with `experimentalAutoDetectLongPolling` and may be removed in a future release. If you find yourself using it to work around a specific network reliability issue, please tell us about it in https://github.com/firebase/firebase-js-sdk/issues/1674. + +Signature: + +```typescript +experimentalForceLongPolling?: boolean; +``` + +## FirestoreSettings.host + +The hostname to connect to. + +Signature: + +```typescript +host?: string; +``` + +## FirestoreSettings.ignoreUndefinedProperties + +Whether to skip nested properties that are set to `undefined` during object serialization. If set to `true`, these properties are skipped and not written to Firestore. If set to `false` or omitted, the SDK throws an exception when it encounters properties of type `undefined`. + +Signature: + +```typescript +ignoreUndefinedProperties?: boolean; +``` + +## FirestoreSettings.ssl + +Whether to use SSL when connecting. + +Signature: + +```typescript +ssl?: boolean; +``` diff --git a/docs-devsite/firestore_.geopoint.md b/docs-devsite/firestore_.geopoint.md new file mode 100644 index 00000000000..d2fd1bd7392 --- /dev/null +++ b/docs-devsite/firestore_.geopoint.md @@ -0,0 +1,117 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# GeoPoint class +An immutable object representing a geographic location in Firestore. The location is represented as latitude/longitude pair. + +Latitude values are in the range of \[-90, 90\]. Longitude values are in the range of \[-180, 180\]. + +Signature: + +```typescript +export declare class GeoPoint +``` + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(latitude, longitude)](./firestore_.geopoint.md#geopointconstructor) | | Creates a new immutable GeoPoint object with the provided latitude and longitude values. | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [latitude](./firestore_.geopoint.md#geopointlatitude) | | number | The latitude of this GeoPoint instance. | +| [longitude](./firestore_.geopoint.md#geopointlongitude) | | number | The longitude of this GeoPoint instance. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [isEqual(other)](./firestore_.geopoint.md#geopointisequal) | | Returns true if this GeoPoint is equal to the provided one. | +| [toJSON()](./firestore_.geopoint.md#geopointtojson) | | Returns a JSON-serializable representation of this GeoPoint. | + +## GeoPoint.(constructor) + +Creates a new immutable `GeoPoint` object with the provided latitude and longitude values. + +Signature: + +```typescript +constructor(latitude: number, longitude: number); +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| latitude | number | The latitude as number between -90 and 90. | +| longitude | number | The longitude as number between -180 and 180. | + +## GeoPoint.latitude + +The latitude of this `GeoPoint` instance. + +Signature: + +```typescript +get latitude(): number; +``` + +## GeoPoint.longitude + +The longitude of this `GeoPoint` instance. + +Signature: + +```typescript +get longitude(): number; +``` + +## GeoPoint.isEqual() + +Returns true if this `GeoPoint` is equal to the provided one. + +Signature: + +```typescript +isEqual(other: GeoPoint): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| other | [GeoPoint](./firestore_.geopoint.md#geopoint_class) | The GeoPoint to compare against. | + +Returns: + +boolean + +true if this `GeoPoint` is equal to the provided one. + +## GeoPoint.toJSON() + +Returns a JSON-serializable representation of this GeoPoint. + +Signature: + +```typescript +toJSON(): { + latitude: number; + longitude: number; + }; +``` +Returns: + +{ latitude: number; longitude: number; } + diff --git a/docs-devsite/firestore_.index.md b/docs-devsite/firestore_.index.md new file mode 100644 index 00000000000..3ea216d6798 --- /dev/null +++ b/docs-devsite/firestore_.index.md @@ -0,0 +1,55 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Index interface +> 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. +> + +The SDK definition of a Firestore index. + +Signature: + +```typescript +export declare interface Index +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [collectionGroup](./firestore_.index.md#indexcollectiongroup) | string | (BETA) The ID of the collection to index. | +| [fields](./firestore_.index.md#indexfields) | [IndexField](./firestore_.indexfield.md#indexfield_interface)\[\] | (BETA) A list of fields to index. | + +## Index.collectionGroup + +> 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. +> + +The ID of the collection to index. + +Signature: + +```typescript +readonly collectionGroup: string; +``` + +## Index.fields + +> 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. +> + +A list of fields to index. + +Signature: + +```typescript +readonly fields?: IndexField[]; +``` diff --git a/docs-devsite/firestore_.indexconfiguration.md b/docs-devsite/firestore_.indexconfiguration.md new file mode 100644 index 00000000000..8a0592e7ed6 --- /dev/null +++ b/docs-devsite/firestore_.indexconfiguration.md @@ -0,0 +1,43 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# IndexConfiguration interface +> 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. +> + +A list of Firestore indexes to speed up local query execution. + +See [JSON Format](https://firebase.google.com/docs/reference/firestore/indexes/#json_format) for a description of the format of the index definition. + +Signature: + +```typescript +export declare interface IndexConfiguration +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [indexes](./firestore_.indexconfiguration.md#indexconfigurationindexes) | [Index](./firestore_.index.md#index_interface)\[\] | (BETA) A list of all Firestore indexes. | + +## IndexConfiguration.indexes + +> 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. +> + +A list of all Firestore indexes. + +Signature: + +```typescript +readonly indexes?: Index[]; +``` diff --git a/docs-devsite/firestore_.indexfield.md b/docs-devsite/firestore_.indexfield.md new file mode 100644 index 00000000000..278e2f63ce8 --- /dev/null +++ b/docs-devsite/firestore_.indexfield.md @@ -0,0 +1,73 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# IndexField interface +> 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. +> + +A single field element in an index configuration. + +Signature: + +```typescript +export declare interface IndexField +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [arrayConfig](./firestore_.indexfield.md#indexfieldarrayconfig) | 'CONTAINS' | (BETA) What type of array index to create. Set to CONTAINS for array-contains and array-contains-any indexes.Only one of arrayConfig or order should be set; | +| [fieldPath](./firestore_.indexfield.md#indexfieldfieldpath) | string | (BETA) The field path to index. | +| [order](./firestore_.indexfield.md#indexfieldorder) | 'ASCENDING' \| 'DESCENDING' | (BETA) What type of array index to create. Set to ASCENDING or 'DESCENDING for ==, !=, <=, <=, in and not-in\` filters.Only one of arrayConfig or order should be set. | + +## IndexField.arrayConfig + +> 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. +> + +What type of array index to create. Set to `CONTAINS` for `array-contains` and `array-contains-any` indexes. + +Only one of `arrayConfig` or `order` should be set; + +Signature: + +```typescript +readonly arrayConfig?: 'CONTAINS'; +``` + +## IndexField.fieldPath + +> 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. +> + +The field path to index. + +Signature: + +```typescript +readonly fieldPath: string; +``` + +## IndexField.order + +> 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. +> + +What type of array index to create. Set to `ASCENDING` or 'DESCENDING` for `==`, `!=`, `<=`, `<=`, `in` and `not-in\` filters. + +Only one of `arrayConfig` or `order` should be set. + +Signature: + +```typescript +readonly order?: 'ASCENDING' | 'DESCENDING'; +``` diff --git a/docs-devsite/firestore_.loadbundletask.md b/docs-devsite/firestore_.loadbundletask.md new file mode 100644 index 00000000000..8b446d5d6e1 --- /dev/null +++ b/docs-devsite/firestore_.loadbundletask.md @@ -0,0 +1,94 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# LoadBundleTask class +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`. + +Signature: + +```typescript +export declare class LoadBundleTask implements PromiseLike +``` +Implements: PromiseLike<[LoadBundleTaskProgress](./firestore_.loadbundletaskprogress.md#loadbundletaskprogress_interface)> + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [catch(onRejected)](./firestore_.loadbundletask.md#loadbundletaskcatch) | | Implements the Promise<LoadBundleTaskProgress>.catch interface. | +| [onProgress(next, error, complete)](./firestore_.loadbundletask.md#loadbundletaskonprogress) | | Registers functions to listen to bundle loading progress events. | +| [then(onFulfilled, onRejected)](./firestore_.loadbundletask.md#loadbundletaskthen) | | Implements the Promise<LoadBundleTaskProgress>.then interface. | + +## LoadBundleTask.catch() + +Implements the `Promise.catch` interface. + +Signature: + +```typescript +catch(onRejected: (a: Error) => R | PromiseLike): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| onRejected | (a: Error) => R \| PromiseLike<R> | Called when an error occurs during bundle loading. | + +Returns: + +Promise<R \| [LoadBundleTaskProgress](./firestore_.loadbundletaskprogress.md#loadbundletaskprogress_interface)> + +## LoadBundleTask.onProgress() + +Registers functions to listen to bundle loading progress events. + +Signature: + +```typescript +onProgress(next?: (progress: LoadBundleTaskProgress) => unknown, error?: (err: Error) => unknown, complete?: () => void): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| next | (progress: [LoadBundleTaskProgress](./firestore_.loadbundletaskprogress.md#loadbundletaskprogress_interface)) => unknown | Called when there is a progress update from bundle loading. Typically next calls occur each time a Firestore document is loaded from the bundle. | +| error | (err: Error) => unknown | Called when an error occurs during bundle loading. The task aborts after reporting the error, and there should be no more updates after this. | +| complete | () => void | Called when the loading task is complete. | + +Returns: + +void + +## LoadBundleTask.then() + +Implements the `Promise.then` interface. + +Signature: + +```typescript +then(onFulfilled?: (a: LoadBundleTaskProgress) => T | PromiseLike, onRejected?: (a: Error) => R | PromiseLike): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| onFulfilled | (a: [LoadBundleTaskProgress](./firestore_.loadbundletaskprogress.md#loadbundletaskprogress_interface)) => T \| PromiseLike<T> | Called on the completion of the loading task with a final LoadBundleTaskProgress update. The update will always have its taskState set to "Success". | +| onRejected | (a: Error) => R \| PromiseLike<R> | Called when an error occurs during bundle loading. | + +Returns: + +Promise<T \| R> + diff --git a/docs-devsite/firestore_.loadbundletaskprogress.md b/docs-devsite/firestore_.loadbundletaskprogress.md new file mode 100644 index 00000000000..98124754928 --- /dev/null +++ b/docs-devsite/firestore_.loadbundletaskprogress.md @@ -0,0 +1,79 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# LoadBundleTaskProgress interface +Represents a progress update or a final state from loading bundles. + +Signature: + +```typescript +export declare interface LoadBundleTaskProgress +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [bytesLoaded](./firestore_.loadbundletaskprogress.md#loadbundletaskprogressbytesloaded) | number | How many bytes have been loaded. | +| [documentsLoaded](./firestore_.loadbundletaskprogress.md#loadbundletaskprogressdocumentsloaded) | number | How many documents have been loaded. | +| [taskState](./firestore_.loadbundletaskprogress.md#loadbundletaskprogresstaskstate) | [TaskState](./firestore_.md#taskstate) | Current task state. | +| [totalBytes](./firestore_.loadbundletaskprogress.md#loadbundletaskprogresstotalbytes) | number | How many bytes are in the bundle being loaded. | +| [totalDocuments](./firestore_.loadbundletaskprogress.md#loadbundletaskprogresstotaldocuments) | number | How many documents are in the bundle being loaded. | + +## LoadBundleTaskProgress.bytesLoaded + +How many bytes have been loaded. + +Signature: + +```typescript +bytesLoaded: number; +``` + +## LoadBundleTaskProgress.documentsLoaded + +How many documents have been loaded. + +Signature: + +```typescript +documentsLoaded: number; +``` + +## LoadBundleTaskProgress.taskState + +Current task state. + +Signature: + +```typescript +taskState: TaskState; +``` + +## LoadBundleTaskProgress.totalBytes + +How many bytes are in the bundle being loaded. + +Signature: + +```typescript +totalBytes: number; +``` + +## LoadBundleTaskProgress.totalDocuments + +How many documents are in the bundle being loaded. + +Signature: + +```typescript +totalDocuments: number; +``` diff --git a/docs-devsite/firestore_.md b/docs-devsite/firestore_.md new file mode 100644 index 00000000000..4a5c2dd49b2 --- /dev/null +++ b/docs-devsite/firestore_.md @@ -0,0 +1,2134 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# @firebase/firestore + +## Functions + +| Function | Description | +| --- | --- | +| 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. | +| [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. | +| [collection(firestore, path, pathSegments)](./firestore_.md#collection) | Gets a CollectionReference instance that refers to the collection at the specified absolute path. | +| [collectionGroup(firestore, collectionId)](./firestore_.md#collectiongroup) | Creates and returns a new Query instance that includes all documents in the database that are contained in a collection or subcollection with the given collectionId. | +| [connectFirestoreEmulator(firestore, host, port, options)](./firestore_.md#connectfirestoreemulator) | Modify this instance to communicate with the Cloud Firestore emulator.Note: This must be called before this instance has been used to do any operations. | +| [disableNetwork(firestore)](./firestore_.md#disablenetwork) | Disables network usage for this instance. It can be re-enabled via [enableNetwork()](./firestore_.md#enablenetwork). While the network is disabled, any snapshot listeners, getDoc() or getDocs() calls will return results from cache, and any write operations will be queued until the network is restored. | +| [doc(firestore, path, pathSegments)](./firestore_.md#doc) | Gets a DocumentReference instance that refers to the document at the specified absolute path. | +| [enableIndexedDbPersistence(firestore, persistenceSettings)](./firestore_.md#enableindexeddbpersistence) | Attempts to enable persistent storage, if possible.Must be called before any other functions (other than [initializeFirestore()](./firestore_.md#initializefirestore), [getFirestore()](./firestore_.md#getfirestore) or [clearIndexedDbPersistence()](./firestore_.md#clearindexeddbpersistence).If this fails, enableIndexedDbPersistence() will reject the promise it returns. Note that even after this failure, the [Firestore](./firestore_.firestore.md#firestore_class) instance will remain usable, however offline persistence will be disabled.There are several reasons why this can fail, which can be identified by the code on the error.\* failed-precondition: The app is already open in another browser tab. \* unimplemented: The browser is incompatible with the offline persistence implementation. | +| [enableMultiTabIndexedDbPersistence(firestore)](./firestore_.md#enablemultitabindexeddbpersistence) | Attempts to enable multi-tab persistent storage, if possible. If enabled across all tabs, all operations share access to local persistence, including shared execution of queries and latency-compensated local document updates across all connected instances.If this fails, enableMultiTabIndexedDbPersistence() will reject the promise it returns. Note that even after this failure, the [Firestore](./firestore_.firestore.md#firestore_class) instance will remain usable, however offline persistence will be disabled.There are several reasons why this can fail, which can be identified by the code on the error.\* failed-precondition: The app is already open in another browser tab and multi-tab is not enabled. \* unimplemented: The browser is incompatible with the offline persistence implementation. | +| [enableNetwork(firestore)](./firestore_.md#enablenetwork) | Re-enables use of the network for this [Firestore](./firestore_.firestore.md#firestore_class) instance after a prior call to [disableNetwork()](./firestore_.md#disablenetwork). | +| [loadBundle(firestore, bundleData)](./firestore_.md#loadbundle) | Loads a Firestore bundle into the local cache. | +| [namedQuery(firestore, name)](./firestore_.md#namedquery) | Reads a Firestore [Query](./firestore_.query.md#query_class) 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](./firestore_.query.md#query_class) by name. | +| [onSnapshotsInSync(firestore, observer)](./firestore_.md#onsnapshotsinsync) | Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners.NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use SnapshotMetadata in the individual listeners to determine if a snapshot is from the cache or the server. | +| [onSnapshotsInSync(firestore, onSync)](./firestore_.md#onsnapshotsinsync) | Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners.NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use SnapshotMetadata in the individual listeners to determine if a snapshot is from the cache or the server. | +| [runTransaction(firestore, updateFunction, options)](./firestore_.md#runtransaction) | Executes the given updateFunction and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, Cloud Firestore retries the updateFunction. If it fails to commit after 5 attempts, the transaction fails.The maximum number of writes allowed in a single transaction is 500. | +| [setIndexConfiguration(firestore, configuration)](./firestore_.md#setindexconfiguration) | (BETA) Configures indexing for local query execution. Any previous index configuration is overridden. The Promise resolves once the index configuration has been persisted.The index entries themselves are created asynchronously. You can continue to use queries that require indexing even if the indices are not yet available. Query execution will automatically start using the index once the index entries have been written.Indexes are only supported with IndexedDb persistence. Invoke either enableIndexedDbPersistence() or enableMultiTabIndexedDbPersistence() before setting an index configuration. If IndexedDb is not enabled, any index configuration is ignored. | +| [setIndexConfiguration(firestore, json)](./firestore_.md#setindexconfiguration) | (BETA) Configures indexing for local query execution. Any previous index configuration is overridden. The Promise resolves once the index configuration has been persisted.The index entries themselves are created asynchronously. You can continue to use queries that require indexing even if the indices are not yet available. Query execution will automatically start using the index once the index entries have been written.Indexes are only supported with IndexedDb persistence. Invoke either enableIndexedDbPersistence() or enableMultiTabIndexedDbPersistence() before setting an index configuration. If IndexedDb is not enabled, any index configuration is ignored.The method accepts the JSON format exported by the Firebase CLI (firebase firestore:indexes). If the JSON format is invalid, this method throws an error. | +| [terminate(firestore)](./firestore_.md#terminate) | Terminates the provided [Firestore](./firestore_.firestore.md#firestore_class) instance.After calling terminate() only the clearIndexedDbPersistence() function may be used. Any other function will throw a FirestoreError.To restart after termination, create a new instance of FirebaseFirestore with [getFirestore()](./firestore_.md#getfirestore).Termination does not cancel any pending writes, and any promises that are awaiting a response from the server will not be resolved. If you have persistence enabled, the next time you start this instance, it will resume sending these writes to the server.Note: Under normal circumstances, calling terminate() is not required. This function is useful only when you want to force this instance to release all of its resources or in combination with clearIndexedDbPersistence() to ensure that all local state is destroyed between test runs. | +| [waitForPendingWrites(firestore)](./firestore_.md#waitforpendingwrites) | Waits until all currently pending writes for the active user have been acknowledged by the backend.The returned promise resolves immediately if there are no outstanding writes. Otherwise, the promise waits for all previously issued writes (including those written in a previous app session), but it does not wait for writes that were added after the function is called. If you want to wait for additional writes, call waitForPendingWrites() again.Any outstanding waitForPendingWrites() promises are rejected during user changes. | +| [writeBatch(firestore)](./firestore_.md#writebatch) | Creates a write batch, used for performing multiple writes as a single atomic operation. The maximum number of writes allowed in a single [WriteBatch](./firestore_.writebatch.md#writebatch_class) is 500.Unlike transactions, write batches are persisted offline and therefore are preferable when you don't need to condition your writes on read data. | +| function() | +| [deleteField()](./firestore_.md#deletefield) | Returns a sentinel for use with [updateDoc()](./firestore_lite.md#updatedoc) or [setDoc()](./firestore_lite.md#setdoc) with {merge: true} to mark a field for deletion. | +| [documentId()](./firestore_.md#documentid) | Returns a special sentinel FieldPath to refer to the ID of a document. It can be used in queries to sort or filter by the document ID. | +| [getFirestore()](./firestore_.md#getfirestore) | Returns the existing default [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. | +| [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(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. | +| function(fieldPath...) | +| [orderBy(fieldPath, directionStr)](./firestore_.md#orderby) | Creates a [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class) that sorts the query result by the specified field, optionally in descending order instead of ascending.Note: Documents that do not contain the specified field will not be present in the query result. | +| [where(fieldPath, opStr, value)](./firestore_.md#where) | Creates a [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) that enforces that documents must contain the specified field and that the value should satisfy the relation constraint provided. | +| function(fieldValues...) | +| [endAt(fieldValues)](./firestore_.md#endat) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | +| [endBefore(fieldValues)](./firestore_.md#endbefore) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | +| [startAfter(fieldValues)](./firestore_.md#startafter) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | +| [startAt(fieldValues)](./firestore_.md#startat) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | +| function(left...) | +| [aggregateQuerySnapshotEqual(left, right)](./firestore_.md#aggregatequerysnapshotequal) | Compares two AggregateQuerySnapshot instances for equality.Two AggregateQuerySnapshot instances are considered "equal" if they have underlying queries that compare equal, and the same data. | +| [queryEqual(left, right)](./firestore_.md#queryequal) | Returns true if the provided queries point to the same collection and apply the same constraints. | +| [refEqual(left, right)](./firestore_.md#refequal) | Returns true if the provided references are equal. | +| [snapshotEqual(left, right)](./firestore_.md#snapshotequal) | Returns true if the provided snapshots are equal. | +| function(limit...) | +| [limit(limit)](./firestore_.md#limit) | Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the first matching documents. | +| [limitToLast(limit)](./firestore_.md#limittolast) | Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the last matching documents.You must specify at least one orderBy clause for limitToLast queries, otherwise an exception will be thrown during execution. | +| function(logLevel...) | +| [setLogLevel(logLevel)](./firestore_.md#setloglevel) | Sets the verbosity of Cloud Firestore logs (debug, error, or silent). | +| function(n...) | +| [increment(n)](./firestore_.md#increment) | 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 increment the field's current value by the given value.If either the operand or the current field value uses floating point precision, all arithmetic follows IEEE 754 semantics. If both values are integers, values outside of JavaScript's safe number range (Number.MIN_SAFE_INTEGER to Number.MAX_SAFE_INTEGER) are also subject to precision loss. Furthermore, once processed by the Firestore backend, all integer operations are capped between -2^63 and 2^63-1.If the current field value is not of type number, or if the field does not yet exist, the transformation sets the field to the given value. | +| function(query...) | +| [getCountFromServer(query)](./firestore_.md#getcountfromserver) | Calculates the number of documents in the result set of the given query, without actually downloading the documents.Using this function to count the documents is efficient because only the final count, not the documents' data, is downloaded. This function can even count the documents if the result set would be prohibitively large to download entirely (e.g. thousands of documents).The result received from the server is presented, unaltered, without considering any local state. That is, documents in the local cache are not taken into consideration, neither are local modifications not yet synchronized with the server. Previously-downloaded results, if any, are not used: every request using this source necessarily involves a round trip to the server. | +| [getDocs(query)](./firestore_.md#getdocs) | Executes the query and returns the results as a QuerySnapshot.Note: getDocs() attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. To specify this behavior, invoke [getDocsFromCache()](./firestore_.md#getdocsfromcache) or [getDocsFromServer()](./firestore_.md#getdocsfromserver). | +| [getDocsFromCache(query)](./firestore_.md#getdocsfromcache) | Executes the query and returns the results as a QuerySnapshot from cache. Returns an empty result set if no documents matching the query are currently cached. | +| [getDocsFromServer(query)](./firestore_.md#getdocsfromserver) | Executes the query and returns the results as a QuerySnapshot from the server. Returns an error if the network is not available. | +| [onSnapshot(query, observer)](./firestore_.md#onsnapshot) | Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | +| [onSnapshot(query, options, observer)](./firestore_.md#onsnapshot) | Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | +| [onSnapshot(query, onNext, onError, onCompletion)](./firestore_.md#onsnapshot) | Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | +| [onSnapshot(query, options, onNext, onError, onCompletion)](./firestore_.md#onsnapshot) | Attaches a listener for QuerySnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks. The listener can be cancelled by calling the function that is returned when onSnapshot is called.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | +| [query(query, queryConstraints)](./firestore_.md#query) | Creates a new immutable instance of [Query](./firestore_.query.md#query_class) that is extended to also include additional query constraints. | +| function(reference...) | +| [addDoc(reference, data)](./firestore_.md#adddoc) | Add a new document to specified CollectionReference with the given data, assigning it a document ID automatically. | +| [collection(reference, path, pathSegments)](./firestore_.md#collection) | Gets a CollectionReference instance that refers to a subcollection of reference at the the specified relative path. | +| [collection(reference, path, pathSegments)](./firestore_.md#collection) | Gets a CollectionReference instance that refers to a subcollection of reference at the the specified relative path. | +| [deleteDoc(reference)](./firestore_.md#deletedoc) | Deletes the document referred to by the specified DocumentReference. | +| [doc(reference, path, pathSegments)](./firestore_.md#doc) | Gets a DocumentReference instance that refers to a document within reference at the specified relative path. If no path is specified, an automatically-generated unique ID will be used for the returned DocumentReference. | +| [doc(reference, path, pathSegments)](./firestore_.md#doc) | Gets a DocumentReference instance that refers to a document within reference at the specified relative path. | +| [getDoc(reference)](./firestore_.md#getdoc) | Reads the document referred to by this DocumentReference.Note: getDoc() attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. To specify this behavior, invoke [getDocFromCache()](./firestore_.md#getdocfromcache) or [getDocFromServer()](./firestore_.md#getdocfromserver). | +| [getDocFromCache(reference)](./firestore_.md#getdocfromcache) | Reads the document referred to by this DocumentReference from cache. Returns an error if the document is not currently cached. | +| [getDocFromServer(reference)](./firestore_.md#getdocfromserver) | Reads the document referred to by this DocumentReference from the server. Returns an error if the network is not available. | +| [onSnapshot(reference, observer)](./firestore_.md#onsnapshot) | Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | +| [onSnapshot(reference, options, observer)](./firestore_.md#onsnapshot) | Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | +| [onSnapshot(reference, onNext, onError, onCompletion)](./firestore_.md#onsnapshot) | Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | +| [onSnapshot(reference, options, onNext, onError, onCompletion)](./firestore_.md#onsnapshot) | Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending. | +| [setDoc(reference, data)](./firestore_.md#setdoc) | Writes to the document referred to by this DocumentReference. If the document does not yet exist, it will be created. | +| [setDoc(reference, data, options)](./firestore_.md#setdoc) | Writes to the document referred to by the specified DocumentReference. If the document does not yet exist, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document. | +| [updateDoc(reference, data)](./firestore_.md#updatedoc) | Updates fields in the document referred to by the specified DocumentReference. The update will fail if applied to a document that does not exist. | +| [updateDoc(reference, field, value, moreFieldsAndValues)](./firestore_.md#updatedoc) | Updates fields in the document referred to by the specified DocumentReference The update will fail if applied to a document that does not exist.Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects. | +| function(snapshot...) | +| [endAt(snapshot)](./firestore_.md#endat) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided document (inclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | +| [endBefore(snapshot)](./firestore_.md#endbefore) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | +| [startAfter(snapshot)](./firestore_.md#startafter) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | +| [startAt(snapshot)](./firestore_.md#startat) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of this query. | + +## Classes + +| Class | Description | +| --- | --- | +| [AggregateField](./firestore_.aggregatefield.md#aggregatefield_class) | Represents an aggregation that can be performed by Firestore. | +| [AggregateQuerySnapshot](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshot_class) | The results of executing an aggregation query. | +| [Bytes](./firestore_.bytes.md#bytes_class) | An immutable object representing an array of bytes. | +| [CollectionReference](./firestore_.collectionreference.md#collectionreference_class) | A CollectionReference object can be used for adding documents, getting document references, and querying for documents (using [query()](./firestore_.md#query)). | +| [DocumentReference](./firestore_.documentreference.md#documentreference_class) | A DocumentReference refers to a document location in a Firestore database and can be used to write, read, or listen to the location. The document at the referenced location may or may not exist. | +| [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class) | A DocumentSnapshot contains data read from a document in your Firestore database. The data can be extracted with .data() or .get(<field>) to get a specific field.For a DocumentSnapshot that points to a non-existing document, any data access will return 'undefined'. You can use the exists() method to explicitly verify a document's existence. | +| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | A FieldPath refers to a field in a document. The path may consist of a single field name (referring to a top-level field in the document), or a list of field names (referring to a nested field in the document).Create a FieldPath by providing field names. If more than one field name is provided, the path will point to a nested field in a document. | +| [FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) | Sentinel values that can be used when writing document fields with set() or update(). | +| [Firestore](./firestore_.firestore.md#firestore_class) | The Cloud Firestore service interface.Do not call this constructor directly. Instead, use [getFirestore()](./firestore_.md#getfirestore). | +| [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class) | An error returned by a Firestore operation. | +| [GeoPoint](./firestore_.geopoint.md#geopoint_class) | An immutable object representing a geographic location in Firestore. The location is represented as latitude/longitude pair.Latitude values are in the range of \[-90, 90\]. Longitude values are in the range of \[-180, 180\]. | +| [LoadBundleTask](./firestore_.loadbundletask.md#loadbundletask_class) | 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>. | +| [Query](./firestore_.query.md#query_class) | A Query refers to a query which you can read or listen to. You can also construct refined Query objects by adding filters and ordering. | +| [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) | A QueryConstraint is used to narrow the set of documents returned by a Firestore query. QueryConstraints are created by invoking [where()](./firestore_.md#where), [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit), [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryConstraint. | +| [QueryDocumentSnapshot](./firestore_.querydocumentsnapshot.md#querydocumentsnapshot_class) | A QueryDocumentSnapshot contains data read from a document in your Firestore database as part of a query. The document is guaranteed to exist and its data can be extracted with .data() or .get(<field>) to get a specific field.A QueryDocumentSnapshot offers the same API surface as a DocumentSnapshot. Since query results contain only existing documents, the exists property will always be true and data() will never return 'undefined'. | +| [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) | A QueryEndAtConstraint is used to exclude documents from the end of a result set returned by a Firestore query. QueryEndAtConstraints are created by invoking [endAt()](./firestore_.md#endat) or [endBefore()](./firestore_.md#endbefore) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryEndAtConstraint. | +| [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) | A QueryFieldFilterConstraint is used to narrow the set of documents returned by a Firestore query by filtering on one or more document fields. QueryFieldFilterConstraints are created by invoking [where()](./firestore_.md#where) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryFieldFilterConstraint. | +| [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) | A QueryLimitConstraint is used to limit the number of documents returned by a Firestore query. QueryLimitConstraints are created by invoking [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryLimitConstraint. | +| [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class) | A QueryOrderByConstraint is used to sort the set of documents returned by a Firestore query. QueryOrderByConstraints are created by invoking [orderBy()](./firestore_.md#orderby) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryOrderByConstraint.Note: Documents that do not contain the orderBy field will not be present in the query result. | +| [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class) | A QuerySnapshot contains zero or more DocumentSnapshot objects representing the results of a query. The documents can be accessed as an array via the docs property or enumerated using the forEach method. The number of documents can be determined via the empty and size properties. | +| [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) | A QueryStartAtConstraint is used to exclude documents from the start of a result set returned by a Firestore query. QueryStartAtConstraints are created by invoking [startAt()](./firestore_.md#startat) or [startAfter()](./firestore_.md#startafter) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryStartAtConstraint. | +| [SnapshotMetadata](./firestore_.snapshotmetadata.md#snapshotmetadata_class) | Metadata about a snapshot, describing the state of the snapshot. | +| [Timestamp](./firestore_.timestamp.md#timestamp_class) | A Timestamp represents a point in time independent of any time zone or calendar, represented as seconds and fractions of seconds at nanosecond resolution in UTC Epoch time.It is encoded using the Proleptic Gregorian Calendar which extends the Gregorian calendar backwards to year one. It is encoded assuming all minutes are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.For examples and further specifications, refer to the [Timestamp definition](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto). | +| [Transaction](./firestore_.transaction.md#transaction_class) | A reference to a transaction.The Transaction object passed to a transaction's updateFunction provides the methods to read and write data within the transaction context. See [runTransaction()](./firestore_.md#runtransaction). | +| [WriteBatch](./firestore_.writebatch.md#writebatch_class) | A write batch, used to perform multiple writes as a single atomic unit.A WriteBatch object can be acquired by calling [writeBatch()](./firestore_.md#writebatch). It provides methods for adding writes to the write batch. None of the writes will be committed (or visible locally) until [WriteBatch.commit()](./firestore_.writebatch.md#writebatchcommit) is called. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [AggregateSpec](./firestore_.aggregatespec.md#aggregatespec_interface) | A type whose property values are all AggregateField objects. | +| [DocumentChange](./firestore_.documentchange.md#documentchange_interface) | A DocumentChange represents a change to the documents matching a query. It contains the document affected and the type of change that occurred. | +| [DocumentData](./firestore_.documentdata.md#documentdata_interface) | Document data (for use with [setDoc()](./firestore_lite.md#setdoc)) consists of fields mapped to values. | +| [FirestoreDataConverter](./firestore_.firestoredataconverter.md#firestoredataconverter_interface) | Converter used by withConverter() to transform user objects of type T into Firestore data.Using the converter allows you to specify generic type arguments when storing and retrieving objects from Firestore. | +| [FirestoreSettings](./firestore_.firestoresettings.md#firestoresettings_interface) | Specifies custom configurations for your Cloud Firestore instance. You must set these before invoking any other methods. | +| [Index](./firestore_.index.md#index_interface) | (BETA) The SDK definition of a Firestore index. | +| [IndexConfiguration](./firestore_.indexconfiguration.md#indexconfiguration_interface) | (BETA) A list of Firestore indexes to speed up local query execution.See [JSON Format](https://firebase.google.com/docs/reference/firestore/indexes/#json_format) for a description of the format of the index definition. | +| [IndexField](./firestore_.indexfield.md#indexfield_interface) | (BETA) A single field element in an index configuration. | +| [LoadBundleTaskProgress](./firestore_.loadbundletaskprogress.md#loadbundletaskprogress_interface) | Represents a progress update or a final state from loading bundles. | +| [PersistenceSettings](./firestore_.persistencesettings.md#persistencesettings_interface) | Settings that can be passed to enableIndexedDbPersistence() to configure Firestore persistence. | +| [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | An options object that can be passed to [onSnapshot()](./firestore_.md#onsnapshot) and [QuerySnapshot.docChanges()](./firestore_.querysnapshot.md#querysnapshotdocchanges) to control which types of changes to include in the result set. | +| [SnapshotOptions](./firestore_.snapshotoptions.md#snapshotoptions_interface) | Options that configure how data is retrieved from a DocumentSnapshot (for example the desired behavior for server timestamps that have not yet been set to their final value). | +| [TransactionOptions](./firestore_.transactionoptions.md#transactionoptions_interface) | Options to customize transaction behavior. | +| [Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) | A function returned by onSnapshot() that removes the listener when invoked. | + +## Variables + +| Variable | Description | +| --- | --- | +| [CACHE\_SIZE\_UNLIMITED](./firestore_.md#cache_size_unlimited) | Constant used to indicate the LRU garbage collection should be disabled. Set this value as the cacheSizeBytes on the settings passed to the [Firestore](./firestore_.firestore.md#firestore_class) instance. | + +## Type Aliases + +| Type Alias | Description | +| --- | --- | +| [AddPrefixToKeys](./firestore_.md#addprefixtokeys) | Returns a new map where every key is prefixed with the outer key appended to a dot. | +| [AggregateFieldType](./firestore_.md#aggregatefieldtype) | The union of all AggregateField types that are supported by Firestore. | +| [AggregateSpecData](./firestore_.md#aggregatespecdata) | A type whose keys are taken from an AggregateSpec, and whose values are the result of the aggregation performed by the corresponding AggregateField from the input AggregateSpec. | +| [ChildUpdateFields](./firestore_.md#childupdatefields) | Helper for calculating the nested fields for a given type T1. This is needed to distribute union types such as undefined | {...} (happens for optional props) or {a: A} | {b: B}.In this use case, V is used to distribute the union types of T[K] on Record, since T[K] is evaluated as an expression and not distributed.See https://www.typescriptlang.org/docs/handbook/advanced-types.html\#distributive-conditional-types | +| [DocumentChangeType](./firestore_.md#documentchangetype) | The type of a DocumentChange may be 'added', 'removed', or 'modified'. | +| [FirestoreErrorCode](./firestore_.md#firestoreerrorcode) | The set of Firestore status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.mdPossible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (e.g. an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation. | +| [NestedUpdateFields](./firestore_.md#nestedupdatefields) | For each field (e.g. 'bar'), find all nested keys (e.g. {'bar.baz': T1, 'bar.qux': T2}). Intersect them together to make a single map containing all possible keys that are all marked as optional | +| [OrderByDirection](./firestore_.md#orderbydirection) | The direction of a [orderBy()](./firestore_.md#orderby) clause is specified as 'desc' or 'asc' (descending or ascending). | +| [PartialWithFieldValue](./firestore_.md#partialwithfieldvalue) | Similar to Typescript's Partial<T>, but allows nested fields to be omitted and FieldValues to be passed in as property values. | +| [Primitive](./firestore_.md#primitive) | Primitive types. | +| [QueryConstraintType](./firestore_.md#queryconstrainttype) | Describes the different query constraints available in this SDK. | +| [QueryNonFilterConstraint](./firestore_.md#querynonfilterconstraint) | QueryNonFilterConstraint is a helper union type that represents QueryConstraints which are used to narrow or order the set of documents, but that do not explicitly filter on a document field. QueryNonFilterConstraints are created by invoking [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains the QueryConstraint. | +| [SetOptions](./firestore_.md#setoptions) | An options object that configures the behavior of [setDoc()](./firestore_lite.md#setdoc), and calls. These calls can be configured to perform granular merges instead of overwriting the target documents in their entirety by providing a SetOptions with merge: true. | +| [TaskState](./firestore_.md#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. | +| [UnionToIntersection](./firestore_.md#uniontointersection) | Given a union type U = T1 | T2 | ..., returns an intersected type (T1 & T2 & ...).Uses distributive conditional types and inference from conditional types. This works because multiple candidates for the same type variable in contra-variant positions causes an intersection type to be inferred. https://www.typescriptlang.org/docs/handbook/advanced-types.html\#type-inference-in-conditional-types https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection-type | +| [UpdateData](./firestore_.md#updatedata) | Update data (for use with [updateDoc()](./firestore_.md#updatedoc)) that consists of field paths (e.g. 'foo' or 'foo.baz') mapped to values. Fields that contain dots reference nested fields within the document. FieldValues can be passed in as property values. | +| [WhereFilterOp](./firestore_.md#wherefilterop) | Filter conditions in a [where()](./firestore_.md#where) clause are specified using the strings '&lt;', '&lt;=', '==', '!=', '&gt;=', '&gt;', 'array-contains', 'in', 'array-contains-any', and 'not-in'. | +| [WithFieldValue](./firestore_.md#withfieldvalue) | Allows FieldValues to be passed in as a property value while maintaining type safety. | + +## 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. + +Signature: + +```typescript +export declare function getFirestore(app: FirebaseApp): Firestore; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance that the returned [Firestore](./firestore_.firestore.md#firestore_class) instance is associated with. | + +Returns: + +[Firestore](./firestore_.firestore.md#firestore_class) + +The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. + +## 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). + +Signature: + +```typescript +export declare function initializeFirestore(app: FirebaseApp, settings: FirestoreSettings, databaseId?: string): Firestore; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) with which the [Firestore](./firestore_.firestore.md#firestore_class) instance will be associated. | +| settings | [FirestoreSettings](./firestore_.firestoresettings.md#firestoresettings_interface) | A settings object to configure the [Firestore](./firestore_.firestore.md#firestore_class) instance. | +| databaseId | string | The name of database. | + +Returns: + +[Firestore](./firestore_.firestore.md#firestore_class) + +A newly initialized [Firestore](./firestore_.firestore.md#firestore_class) instance. + +## 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. + +Signature: + +```typescript +export declare function clearIndexedDbPersistence(firestore: Firestore): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to clear persistence for. | + +Returns: + +Promise<void> + +A `Promise` that is resolved when the persistent storage is cleared. Otherwise, the promise is rejected with an error. + +## collection() + +Gets a `CollectionReference` instance that refers to the collection at the specified absolute path. + +Signature: + +```typescript +export declare function collection(firestore: Firestore, path: string, ...pathSegments: string[]): CollectionReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | A reference to the root Firestore instance. | +| path | string | A slash-separated path to a collection. | +| pathSegments | string\[\] | Additional path segments to apply relative to the first argument. | + +Returns: + +[CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> + +The `CollectionReference` instance. + +## Exceptions + +If the final path has an even number of segments and does not point to a collection. + +## collectionGroup() + +Creates and returns a new `Query` instance that includes all documents in the database that are contained in a collection or subcollection with the given `collectionId`. + +Signature: + +```typescript +export declare function collectionGroup(firestore: Firestore, collectionId: string): Query; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | A reference to the root Firestore instance. | +| collectionId | string | Identifies the collections to query over. Every collection or subcollection with this ID as the last segment of its path will be included. Cannot contain a slash. | + +Returns: + +[Query](./firestore_.query.md#query_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> + +The created `Query`. + +## connectFirestoreEmulator() + +Modify this instance to communicate with the Cloud Firestore emulator. + +Note: This must be called before this instance has been used to do any operations. + +Signature: + +```typescript +export declare function connectFirestoreEmulator(firestore: Firestore, host: string, port: number, options?: { + mockUserToken?: EmulatorMockTokenOptions | string; +}): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The Firestore instance to configure to connect to the emulator. | +| host | string | the emulator host (ex: localhost). | +| port | number | the emulator port (ex: 9000). | +| options | { mockUserToken?: [EmulatorMockTokenOptions](./util.md#emulatormocktokenoptions) \| string; } | | + +Returns: + +void + +## disableNetwork() + +Disables network usage for this instance. It can be re-enabled via [enableNetwork()](./firestore_.md#enablenetwork). While the network is disabled, any snapshot listeners, `getDoc()` or `getDocs()` calls will return results from cache, and any write operations will be queued until the network is restored. + +Signature: + +```typescript +export declare function disableNetwork(firestore: Firestore): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | + +Returns: + +Promise<void> + +A `Promise` that is resolved once the network has been disabled. + +## doc() + +Gets a `DocumentReference` instance that refers to the document at the specified absolute path. + +Signature: + +```typescript +export declare function doc(firestore: Firestore, path: string, ...pathSegments: string[]): DocumentReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | A reference to the root Firestore instance. | +| path | string | A slash-separated path to a document. | +| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | + +Returns: + +[DocumentReference](./firestore_.documentreference.md#documentreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> + +The `DocumentReference` instance. + +## Exceptions + +If the final path has an odd number of segments and does not point to a document. + +## enableIndexedDbPersistence() + +Attempts to enable persistent storage, if possible. + +Must be called before any other functions (other than [initializeFirestore()](./firestore_.md#initializefirestore), [getFirestore()](./firestore_.md#getfirestore) or [clearIndexedDbPersistence()](./firestore_.md#clearindexeddbpersistence). + +If this fails, `enableIndexedDbPersistence()` will reject the promise it returns. Note that even after this failure, the [Firestore](./firestore_.firestore.md#firestore_class) instance will remain usable, however offline persistence will be disabled. + +There are several reasons why this can fail, which can be identified by the `code` on the error. + +\* failed-precondition: The app is already open in another browser tab. \* unimplemented: The browser is incompatible with the offline persistence implementation. + +Signature: + +```typescript +export declare function enableIndexedDbPersistence(firestore: Firestore, persistenceSettings?: PersistenceSettings): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to enable persistence for. | +| persistenceSettings | [PersistenceSettings](./firestore_.persistencesettings.md#persistencesettings_interface) | Optional settings object to configure persistence. | + +Returns: + +Promise<void> + +A `Promise` that represents successfully enabling persistent storage. + +## enableMultiTabIndexedDbPersistence() + +Attempts to enable multi-tab persistent storage, if possible. If enabled across all tabs, all operations share access to local persistence, including shared execution of queries and latency-compensated local document updates across all connected instances. + +If this fails, `enableMultiTabIndexedDbPersistence()` will reject the promise it returns. Note that even after this failure, the [Firestore](./firestore_.firestore.md#firestore_class) instance will remain usable, however offline persistence will be disabled. + +There are several reasons why this can fail, which can be identified by the `code` on the error. + +\* failed-precondition: The app is already open in another browser tab and multi-tab is not enabled. \* unimplemented: The browser is incompatible with the offline persistence implementation. + +Signature: + +```typescript +export declare function enableMultiTabIndexedDbPersistence(firestore: Firestore): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to enable persistence for. | + +Returns: + +Promise<void> + +A `Promise` that represents successfully enabling persistent storage. + +## enableNetwork() + +Re-enables use of the network for this [Firestore](./firestore_.firestore.md#firestore_class) instance after a prior call to [disableNetwork()](./firestore_.md#disablenetwork). + +Signature: + +```typescript +export declare function enableNetwork(firestore: Firestore): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | + +Returns: + +Promise<void> + +A `Promise` that is resolved once the network has been enabled. + +## loadBundle() + +Loads a Firestore bundle into the local cache. + +Signature: + +```typescript +export declare function loadBundle(firestore: Firestore, bundleData: ReadableStream | ArrayBuffer | string): LoadBundleTask; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to load bundles for. | +| bundleData | ReadableStream<Uint8Array> \| ArrayBuffer \| string | An object representing the bundle to be loaded. Valid objects are ArrayBuffer, ReadableStream<Uint8Array> or string. | + +Returns: + +[LoadBundleTask](./firestore_.loadbundletask.md#loadbundletask_class) + +A `LoadBundleTask` object, which notifies callers with progress updates, and completion or error events. It can be used as a `Promise`. + +## namedQuery() + +Reads a Firestore [Query](./firestore_.query.md#query_class) 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](./firestore_.query.md#query_class) by name. + +Signature: + +```typescript +export declare function namedQuery(firestore: Firestore, name: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to read the query from. | +| name | string | The name of the query. | + +Returns: + +Promise<[Query](./firestore_.query.md#query_class) \| null> + +A `Promise` that is resolved with the Query or `null`. + +## onSnapshotsInSync() + +Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners. + +NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use SnapshotMetadata in the individual listeners to determine if a snapshot is from the cache or the server. + +Signature: + +```typescript +export declare function onSnapshotsInSync(firestore: Firestore, observer: { + next?: (value: void) => void; + error?: (error: FirestoreError) => void; + complete?: () => void; +}): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The instance of Firestore for synchronizing snapshots. | +| observer | { next?: (value: void) => void; error?: (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void; complete?: () => void; } | A single object containing next and error callbacks. | + +Returns: + +[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) + +An unsubscribe function that can be called to cancel the snapshot listener. + +## onSnapshotsInSync() + +Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners. + +NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use `SnapshotMetadata` in the individual listeners to determine if a snapshot is from the cache or the server. + +Signature: + +```typescript +export declare function onSnapshotsInSync(firestore: Firestore, onSync: () => void): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The Firestore instance for synchronizing snapshots. | +| onSync | () => void | A callback to be called every time all snapshot listeners are in sync with each other. | + +Returns: + +[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) + +An unsubscribe function that can be called to cancel the snapshot listener. + +## runTransaction() + +Executes the given `updateFunction` and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, Cloud Firestore retries the `updateFunction`. If it fails to commit after 5 attempts, the transaction fails. + +The maximum number of writes allowed in a single transaction is 500. + +Signature: + +```typescript +export declare function runTransaction(firestore: Firestore, updateFunction: (transaction: Transaction) => Promise, options?: TransactionOptions): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | A reference to the Firestore database to run this transaction against. | +| updateFunction | (transaction: [Transaction](./firestore_.transaction.md#transaction_class)) => Promise<T> | The function to execute within the transaction context. | +| options | [TransactionOptions](./firestore_.transactionoptions.md#transactionoptions_interface) | An options object to configure maximum number of attempts to commit. | + +Returns: + +Promise<T> + +If the transaction completed successfully or was explicitly aborted (the `updateFunction` returned a failed promise), the promise returned by the `updateFunction `is returned here. Otherwise, if the transaction failed, a rejected promise with the corresponding failure error is returned. + +## setIndexConfiguration() + +> 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. +> + +Configures indexing for local query execution. Any previous index configuration is overridden. The `Promise` resolves once the index configuration has been persisted. + +The index entries themselves are created asynchronously. You can continue to use queries that require indexing even if the indices are not yet available. Query execution will automatically start using the index once the index entries have been written. + +Indexes are only supported with IndexedDb persistence. Invoke either `enableIndexedDbPersistence()` or `enableMultiTabIndexedDbPersistence()` before setting an index configuration. If IndexedDb is not enabled, any index configuration is ignored. + +Signature: + +```typescript +export declare function setIndexConfiguration(firestore: Firestore, configuration: IndexConfiguration): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to configure indexes for. | +| configuration | [IndexConfiguration](./firestore_.indexconfiguration.md#indexconfiguration_interface) | The index definition. | + +Returns: + +Promise<void> + +A `Promise` that resolves once all indices are successfully configured. + +## Exceptions + +FirestoreError if the JSON format is invalid. + +## setIndexConfiguration() + +> 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. +> + +Configures indexing for local query execution. Any previous index configuration is overridden. The `Promise` resolves once the index configuration has been persisted. + +The index entries themselves are created asynchronously. You can continue to use queries that require indexing even if the indices are not yet available. Query execution will automatically start using the index once the index entries have been written. + +Indexes are only supported with IndexedDb persistence. Invoke either `enableIndexedDbPersistence()` or `enableMultiTabIndexedDbPersistence()` before setting an index configuration. If IndexedDb is not enabled, any index configuration is ignored. + +The method accepts the JSON format exported by the Firebase CLI (`firebase firestore:indexes`). If the JSON format is invalid, this method throws an error. + +Signature: + +```typescript +export declare function setIndexConfiguration(firestore: Firestore, json: string): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance to configure indexes for. | +| json | string | The JSON format exported by the Firebase CLI. | + +Returns: + +Promise<void> + +A `Promise` that resolves once all indices are successfully configured. + +## Exceptions + +FirestoreError if the JSON format is invalid. + +## terminate() + +Terminates the provided [Firestore](./firestore_.firestore.md#firestore_class) instance. + +After calling `terminate()` only the `clearIndexedDbPersistence()` function may be used. Any other function will throw a `FirestoreError`. + +To restart after termination, create a new instance of FirebaseFirestore with [getFirestore()](./firestore_.md#getfirestore). + +Termination does not cancel any pending writes, and any promises that are awaiting a response from the server will not be resolved. If you have persistence enabled, the next time you start this instance, it will resume sending these writes to the server. + +Note: Under normal circumstances, calling `terminate()` is not required. This function is useful only when you want to force this instance to release all of its resources or in combination with `clearIndexedDbPersistence()` to ensure that all local state is destroyed between test runs. + +Signature: + +```typescript +export declare function terminate(firestore: Firestore): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | + +Returns: + +Promise<void> + +A `Promise` that is resolved when the instance has been successfully terminated. + +## waitForPendingWrites() + +Waits until all currently pending writes for the active user have been acknowledged by the backend. + +The returned promise resolves immediately if there are no outstanding writes. Otherwise, the promise waits for all previously issued writes (including those written in a previous app session), but it does not wait for writes that were added after the function is called. If you want to wait for additional writes, call `waitForPendingWrites()` again. + +Any outstanding `waitForPendingWrites()` promises are rejected during user changes. + +Signature: + +```typescript +export declare function waitForPendingWrites(firestore: Firestore): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | + +Returns: + +Promise<void> + +A `Promise` which resolves when all currently pending writes have been acknowledged by the backend. + +## writeBatch() + +Creates a write batch, used for performing multiple writes as a single atomic operation. The maximum number of writes allowed in a single [WriteBatch](./firestore_.writebatch.md#writebatch_class) is 500. + +Unlike transactions, write batches are persisted offline and therefore are preferable when you don't need to condition your writes on read data. + +Signature: + +```typescript +export declare function writeBatch(firestore: Firestore): WriteBatch; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | + +Returns: + +[WriteBatch](./firestore_.writebatch.md#writebatch_class) + +A [WriteBatch](./firestore_.writebatch.md#writebatch_class) that can be used to atomically execute multiple writes. + +## deleteField() + +Returns a sentinel for use with [updateDoc()](./firestore_lite.md#updatedoc) or [setDoc()](./firestore_lite.md#setdoc) with `{merge: true}` to mark a field for deletion. + +Signature: + +```typescript +export declare function deleteField(): FieldValue; +``` +Returns: + +[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) + +## documentId() + +Returns a special sentinel `FieldPath` to refer to the ID of a document. It can be used in queries to sort or filter by the document ID. + +Signature: + +```typescript +export declare function documentId(): FieldPath; +``` +Returns: + +[FieldPath](./firestore_.fieldpath.md#fieldpath_class) + +## getFirestore() + +Returns the existing default [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: + +```typescript +export declare function getFirestore(): Firestore; +``` +Returns: + +[Firestore](./firestore_.firestore.md#firestore_class) + +The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. + +## 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. + +Signature: + +```typescript +export declare function serverTimestamp(): FieldValue; +``` +Returns: + +[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) + +## 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. + +Signature: + +```typescript +export declare function arrayRemove(...elements: unknown[]): FieldValue; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| elements | unknown\[\] | The elements to remove from the array. | + +Returns: + +[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) + +The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()` + +## 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. + +Signature: + +```typescript +export declare function arrayUnion(...elements: unknown[]): FieldValue; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| elements | unknown\[\] | The elements to union into the array. | + +Returns: + +[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) + +The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()`. + +## orderBy() + +Creates a [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class) that sorts the query result by the specified field, optionally in descending order instead of ascending. + +Note: Documents that do not contain the specified field will not be present in the query result. + +Signature: + +```typescript +export declare function orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDirection): QueryOrderByConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldPath | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The field to sort by. | +| directionStr | [OrderByDirection](./firestore_.md#orderbydirection) | Optional direction to sort by ('asc' or 'desc'). If not specified, order will be ascending. | + +Returns: + +[QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class) + +The created [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class). + +## where() + +Creates a [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) that enforces that documents must contain the specified field and that the value should satisfy the relation constraint provided. + +Signature: + +```typescript +export declare function where(fieldPath: string | FieldPath, opStr: WhereFilterOp, value: unknown): QueryFieldFilterConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldPath | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The path to compare | +| opStr | [WhereFilterOp](./firestore_.md#wherefilterop) | The operation string (e.g "&lt;", "&lt;=", "==", "&lt;", "&lt;=", "!="). | +| value | unknown | The value for comparison | + +Returns: + +[QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) + +The created [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class). + +## endAt() + +Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. + +Signature: + +```typescript +export declare function endAt(...fieldValues: unknown[]): QueryEndAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldValues | unknown\[\] | The field values to end this query at, in order of the query's order by. | + +Returns: + +[QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) + +A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` + +## endBefore() + +Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. + +Signature: + +```typescript +export declare function endBefore(...fieldValues: unknown[]): QueryEndAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldValues | unknown\[\] | The field values to end this query before, in order of the query's order by. | + +Returns: + +[QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) + +A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` + +## startAfter() + +Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. + +Signature: + +```typescript +export declare function startAfter(...fieldValues: unknown[]): QueryStartAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldValues | unknown\[\] | The field values to start this query after, in order of the query's order by. | + +Returns: + +[QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) + +A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()` + +## startAt() + +Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. + +Signature: + +```typescript +export declare function startAt(...fieldValues: unknown[]): QueryStartAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldValues | unknown\[\] | The field values to start this query at, in order of the query's order by. | + +Returns: + +[QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) + +A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()`. + +## aggregateQuerySnapshotEqual() + +Compares two `AggregateQuerySnapshot` instances for equality. + +Two `AggregateQuerySnapshot` instances are considered "equal" if they have underlying queries that compare equal, and the same data. + +Signature: + +```typescript +export declare function aggregateQuerySnapshotEqual(left: AggregateQuerySnapshot, right: AggregateQuerySnapshot): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| left | [AggregateQuerySnapshot](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<T> | The first AggregateQuerySnapshot to compare. | +| right | [AggregateQuerySnapshot](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<T> | The second AggregateQuerySnapshot to compare. | + +Returns: + +boolean + +`true` if the objects are "equal", as defined above, or `false` otherwise. + +## queryEqual() + +Returns true if the provided queries point to the same collection and apply the same constraints. + +Signature: + +```typescript +export declare function queryEqual(left: Query, right: Query): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| left | [Query](./firestore_.query.md#query_class)<T> | A Query to compare. | +| right | [Query](./firestore_.query.md#query_class)<T> | A Query to compare. | + +Returns: + +boolean + +true if the references point to the same location in the same Firestore database. + +## refEqual() + +Returns true if the provided references are equal. + +Signature: + +```typescript +export declare function refEqual(left: DocumentReference | CollectionReference, right: DocumentReference | CollectionReference): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| left | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> \| [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | A reference to compare. | +| right | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> \| [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | A reference to compare. | + +Returns: + +boolean + +true if the references point to the same location in the same Firestore database. + +## snapshotEqual() + +Returns true if the provided snapshots are equal. + +Signature: + +```typescript +export declare function snapshotEqual(left: DocumentSnapshot | QuerySnapshot, right: DocumentSnapshot | QuerySnapshot): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| left | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T> \| [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T> | A snapshot to compare. | +| right | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T> \| [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T> | A snapshot to compare. | + +Returns: + +boolean + +true if the snapshots are equal. + +## limit() + +Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the first matching documents. + +Signature: + +```typescript +export declare function limit(limit: number): QueryLimitConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| limit | number | The maximum number of items to return. | + +Returns: + +[QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) + +The created [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class). + +## limitToLast() + +Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the last matching documents. + +You must specify at least one `orderBy` clause for `limitToLast` queries, otherwise an exception will be thrown during execution. + +Signature: + +```typescript +export declare function limitToLast(limit: number): QueryLimitConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| limit | number | The maximum number of items to return. | + +Returns: + +[QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) + +The created [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class). + +## setLogLevel() + +Sets the verbosity of Cloud Firestore logs (debug, error, or silent). + +Signature: + +```typescript +export declare function setLogLevel(logLevel: LogLevel): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| logLevel | LogLevel | The verbosity you set for activity and error logging. Can be any of the following values:

  • debug for the most verbose logging level, primarily for debugging.
  • error to log errors only.
  • silent to turn off logging.
| + +Returns: + +void + +## increment() + +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 increment the field's current value by the given value. + +If either the operand or the current field value uses floating point precision, all arithmetic follows IEEE 754 semantics. If both values are integers, values outside of JavaScript's safe number range (`Number.MIN_SAFE_INTEGER` to `Number.MAX_SAFE_INTEGER`) are also subject to precision loss. Furthermore, once processed by the Firestore backend, all integer operations are capped between -2^63 and 2^63-1. + +If the current field value is not of type `number`, or if the field does not yet exist, the transformation sets the field to the given value. + +Signature: + +```typescript +export declare function increment(n: number): FieldValue; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| n | number | The value to increment by. | + +Returns: + +[FieldValue](./firestore_.fieldvalue.md#fieldvalue_class) + +The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()` + +## getCountFromServer() + +Calculates the number of documents in the result set of the given query, without actually downloading the documents. + +Using this function to count the documents is efficient because only the final count, not the documents' data, is downloaded. This function can even count the documents if the result set would be prohibitively large to download entirely (e.g. thousands of documents). + +The result received from the server is presented, unaltered, without considering any local state. That is, documents in the local cache are not taken into consideration, neither are local modifications not yet synchronized with the server. Previously-downloaded results, if any, are not used: every request using this source necessarily involves a round trip to the server. + +Signature: + +```typescript +export declare function getCountFromServer(query: Query): Promise; +}>>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./firestore_.query.md#query_class)<unknown> | The query whose result set size to calculate. | + +Returns: + +Promise<[AggregateQuerySnapshot](./firestore_.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<{ count: [AggregateField](./firestore_.aggregatefield.md#aggregatefield_class)<number>; }>> + +A Promise that will be resolved with the count; the count can be retrieved from `snapshot.data().count`, where `snapshot` is the `AggregateQuerySnapshot` to which the returned Promise resolves. + +## getDocs() + +Executes the query and returns the results as a `QuerySnapshot`. + +Note: `getDocs()` attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. To specify this behavior, invoke [getDocsFromCache()](./firestore_.md#getdocsfromcache) or [getDocsFromServer()](./firestore_.md#getdocsfromserver). + +Signature: + +```typescript +export declare function getDocs(query: Query): Promise>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./firestore_.query.md#query_class)<T> | | + +Returns: + +Promise<[QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>> + +A `Promise` that will be resolved with the results of the query. + +## getDocsFromCache() + +Executes the query and returns the results as a `QuerySnapshot` from cache. Returns an empty result set if no documents matching the query are currently cached. + +Signature: + +```typescript +export declare function getDocsFromCache(query: Query): Promise>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./firestore_.query.md#query_class)<T> | | + +Returns: + +Promise<[QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>> + +A `Promise` that will be resolved with the results of the query. + +## getDocsFromServer() + +Executes the query and returns the results as a `QuerySnapshot` from the server. Returns an error if the network is not available. + +Signature: + +```typescript +export declare function getDocsFromServer(query: Query): Promise>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./firestore_.query.md#query_class)<T> | | + +Returns: + +Promise<[QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>> + +A `Promise` that will be resolved with the results of the query. + +## onSnapshot() + +Attaches a listener for `QuerySnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. The listener can be cancelled by calling the function that is returned when `onSnapshot` is called. + +NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. + +Signature: + +```typescript +export declare function onSnapshot(query: Query, observer: { + next?: (snapshot: QuerySnapshot) => void; + error?: (error: FirestoreError) => void; + complete?: () => void; +}): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./firestore_.query.md#query_class)<T> | The query to listen to. | +| observer | { next?: (snapshot: [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>) => void; error?: (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void; complete?: () => void; } | A single object containing next and error callbacks. | + +Returns: + +[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) + +An unsubscribe function that can be called to cancel the snapshot listener. + +## onSnapshot() + +Attaches a listener for `QuerySnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. The listener can be cancelled by calling the function that is returned when `onSnapshot` is called. + +NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. + +Signature: + +```typescript +export declare function onSnapshot(query: Query, options: SnapshotListenOptions, observer: { + next?: (snapshot: QuerySnapshot) => void; + error?: (error: FirestoreError) => void; + complete?: () => void; +}): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./firestore_.query.md#query_class)<T> | The query to listen to. | +| options | [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | Options controlling the listen behavior. | +| observer | { next?: (snapshot: [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>) => void; error?: (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void; complete?: () => void; } | A single object containing next and error callbacks. | + +Returns: + +[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) + +An unsubscribe function that can be called to cancel the snapshot listener. + +## onSnapshot() + +Attaches a listener for `QuerySnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. The listener can be cancelled by calling the function that is returned when `onSnapshot` is called. + +NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. + +Signature: + +```typescript +export declare function onSnapshot(query: Query, onNext: (snapshot: QuerySnapshot) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./firestore_.query.md#query_class)<T> | The query to listen to. | +| onNext | (snapshot: [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>) => void | A callback to be called every time a new QuerySnapshot is available. | +| onError | (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void | A callback to be called if the listen fails or is cancelled. No further callbacks will occur. | +| onCompletion | () => void | Can be provided, but will not be called since streams are never ending. | + +Returns: + +[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) + +An unsubscribe function that can be called to cancel the snapshot listener. + +## onSnapshot() + +Attaches a listener for `QuerySnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. The listener can be cancelled by calling the function that is returned when `onSnapshot` is called. + +NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. + +Signature: + +```typescript +export declare function onSnapshot(query: Query, options: SnapshotListenOptions, onNext: (snapshot: QuerySnapshot) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./firestore_.query.md#query_class)<T> | The query to listen to. | +| options | [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | Options controlling the listen behavior. | +| onNext | (snapshot: [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class)<T>) => void | A callback to be called every time a new QuerySnapshot is available. | +| onError | (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void | A callback to be called if the listen fails or is cancelled. No further callbacks will occur. | +| onCompletion | () => void | Can be provided, but will not be called since streams are never ending. | + +Returns: + +[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) + +An unsubscribe function that can be called to cancel the snapshot listener. + +## query() + +Creates a new immutable instance of [Query](./firestore_.query.md#query_class) that is extended to also include additional query constraints. + +Signature: + +```typescript +export declare function query(query: Query, ...queryConstraints: QueryConstraint[]): Query; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./firestore_.query.md#query_class)<T> | The [Query](./firestore_.query.md#query_class) instance to use as a base for the new constraints. | +| queryConstraints | [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class)\[\] | The list of [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class)s to apply. | + +Returns: + +[Query](./firestore_.query.md#query_class)<T> + +## Exceptions + +if any of the provided query constraints cannot be combined with the existing or new constraints. + +## addDoc() + +Add a new document to specified `CollectionReference` with the given data, assigning it a document ID automatically. + +Signature: + +```typescript +export declare function addDoc(reference: CollectionReference, data: WithFieldValue): Promise>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | A reference to the collection to add this document to. | +| data | [WithFieldValue](./firestore_.md#withfieldvalue)<T> | An Object containing the data for the new document. | + +Returns: + +Promise<[DocumentReference](./firestore_.documentreference.md#documentreference_class)<T>> + +A `Promise` resolved with a `DocumentReference` pointing to the newly created document after it has been written to the backend (Note that it won't resolve while you're offline). + +## collection() + +Gets a `CollectionReference` instance that refers to a subcollection of `reference` at the the specified relative path. + +Signature: + +```typescript +export declare function collection(reference: CollectionReference, path: string, ...pathSegments: string[]): CollectionReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<unknown> | A reference to a collection. | +| path | string | A slash-separated path to a collection. | +| pathSegments | string\[\] | Additional path segments to apply relative to the first argument. | + +Returns: + +[CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> + +The `CollectionReference` instance. + +## Exceptions + +If the final path has an even number of segments and does not point to a collection. + +## collection() + +Gets a `CollectionReference` instance that refers to a subcollection of `reference` at the the specified relative path. + +Signature: + +```typescript +export declare function collection(reference: DocumentReference, path: string, ...pathSegments: string[]): CollectionReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class) | A reference to a Firestore document. | +| path | string | A slash-separated path to a collection. | +| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | + +Returns: + +[CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> + +The `CollectionReference` instance. + +## Exceptions + +If the final path has an even number of segments and does not point to a collection. + +## deleteDoc() + +Deletes the document referred to by the specified `DocumentReference`. + +Signature: + +```typescript +export declare function deleteDoc(reference: DocumentReference): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to the document to delete. | + +Returns: + +Promise<void> + +A Promise resolved once the document has been successfully deleted from the backend (note that it won't resolve while you're offline). + +## doc() + +Gets a `DocumentReference` instance that refers to a document within `reference` at the specified relative path. If no path is specified, an automatically-generated unique ID will be used for the returned `DocumentReference`. + +Signature: + +```typescript +export declare function doc(reference: CollectionReference, path?: string, ...pathSegments: string[]): DocumentReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [CollectionReference](./firestore_.collectionreference.md#collectionreference_class)<T> | A reference to a collection. | +| path | string | A slash-separated path to a document. Has to be omitted to use auto-genrated IDs. | +| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | + +Returns: + +[DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> + +The `DocumentReference` instance. + +## Exceptions + +If the final path has an odd number of segments and does not point to a document. + +## doc() + +Gets a `DocumentReference` instance that refers to a document within `reference` at the specified relative path. + +Signature: + +```typescript +export declare function doc(reference: DocumentReference, path: string, ...pathSegments: string[]): DocumentReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to a Firestore document. | +| path | string | A slash-separated path to a document. | +| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | + +Returns: + +[DocumentReference](./firestore_.documentreference.md#documentreference_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> + +The `DocumentReference` instance. + +## Exceptions + +If the final path has an odd number of segments and does not point to a document. + +## getDoc() + +Reads the document referred to by this `DocumentReference`. + +Note: `getDoc()` attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. To specify this behavior, invoke [getDocFromCache()](./firestore_.md#getdocfromcache) or [getDocFromServer()](./firestore_.md#getdocfromserver). + +Signature: + +```typescript +export declare function getDoc(reference: DocumentReference): Promise>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | The reference of the document to fetch. | + +Returns: + +Promise<[DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>> + +A Promise resolved with a `DocumentSnapshot` containing the current document contents. + +## getDocFromCache() + +Reads the document referred to by this `DocumentReference` from cache. Returns an error if the document is not currently cached. + +Signature: + +```typescript +export declare function getDocFromCache(reference: DocumentReference): Promise>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | | + +Returns: + +Promise<[DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>> + +A `Promise` resolved with a `DocumentSnapshot` containing the current document contents. + +## getDocFromServer() + +Reads the document referred to by this `DocumentReference` from the server. Returns an error if the network is not available. + +Signature: + +```typescript +export declare function getDocFromServer(reference: DocumentReference): Promise>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | | + +Returns: + +Promise<[DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>> + +A `Promise` resolved with a `DocumentSnapshot` containing the current document contents. + +## onSnapshot() + +Attaches a listener for `DocumentSnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. + +NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. + +Signature: + +```typescript +export declare function onSnapshot(reference: DocumentReference, observer: { + next?: (snapshot: DocumentSnapshot) => void; + error?: (error: FirestoreError) => void; + complete?: () => void; +}): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to listen to. | +| observer | { next?: (snapshot: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>) => void; error?: (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void; complete?: () => void; } | A single object containing next and error callbacks. | + +Returns: + +[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) + +An unsubscribe function that can be called to cancel the snapshot listener. + +## onSnapshot() + +Attaches a listener for `DocumentSnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. + +NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. + +Signature: + +```typescript +export declare function onSnapshot(reference: DocumentReference, options: SnapshotListenOptions, observer: { + next?: (snapshot: DocumentSnapshot) => void; + error?: (error: FirestoreError) => void; + complete?: () => void; +}): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to listen to. | +| options | [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | Options controlling the listen behavior. | +| observer | { next?: (snapshot: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>) => void; error?: (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void; complete?: () => void; } | A single object containing next and error callbacks. | + +Returns: + +[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) + +An unsubscribe function that can be called to cancel the snapshot listener. + +## onSnapshot() + +Attaches a listener for `DocumentSnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. + +NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. + +Signature: + +```typescript +export declare function onSnapshot(reference: DocumentReference, onNext: (snapshot: DocumentSnapshot) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to listen to. | +| onNext | (snapshot: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>) => void | A callback to be called every time a new DocumentSnapshot is available. | +| onError | (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void | A callback to be called if the listen fails or is cancelled. No further callbacks will occur. | +| onCompletion | () => void | Can be provided, but will not be called since streams are never ending. | + +Returns: + +[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) + +An unsubscribe function that can be called to cancel the snapshot listener. + +## onSnapshot() + +Attaches a listener for `DocumentSnapshot` events. You may either pass individual `onNext` and `onError` callbacks or pass a single observer object with `next` and `error` callbacks. + +NOTE: Although an `onCompletion` callback can be provided, it will never be called because the snapshot stream is never-ending. + +Signature: + +```typescript +export declare function onSnapshot(reference: DocumentReference, options: SnapshotListenOptions, onNext: (snapshot: DocumentSnapshot) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to listen to. | +| options | [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | Options controlling the listen behavior. | +| onNext | (snapshot: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>) => void | A callback to be called every time a new DocumentSnapshot is available. | +| onError | (error: [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class)) => void | A callback to be called if the listen fails or is cancelled. No further callbacks will occur. | +| onCompletion | () => void | Can be provided, but will not be called since streams are never ending. | + +Returns: + +[Unsubscribe](./firestore_.unsubscribe.md#unsubscribe_interface) + +An unsubscribe function that can be called to cancel the snapshot listener. + +## setDoc() + +Writes to the document referred to by this `DocumentReference`. If the document does not yet exist, it will be created. + +Signature: + +```typescript +export declare function setDoc(reference: DocumentReference, data: WithFieldValue): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to write. | +| data | [WithFieldValue](./firestore_.md#withfieldvalue)<T> | A map of the fields and values for the document. | + +Returns: + +Promise<void> + +A `Promise` resolved once the data has been successfully written to the backend (note that it won't resolve while you're offline). + +## setDoc() + +Writes to the document referred to by the specified `DocumentReference`. If the document does not yet exist, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. + +Signature: + +```typescript +export declare function setDoc(reference: DocumentReference, data: PartialWithFieldValue, options: SetOptions): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to write. | +| data | [PartialWithFieldValue](./firestore_.md#partialwithfieldvalue)<T> | A map of the fields and values for the document. | +| options | [SetOptions](./firestore_.md#setoptions) | An object to configure the set behavior. | + +Returns: + +Promise<void> + +A Promise resolved once the data has been successfully written to the backend (note that it won't resolve while you're offline). + +## updateDoc() + +Updates fields in the document referred to by the specified `DocumentReference`. The update will fail if applied to a document that does not exist. + +Signature: + +```typescript +export declare function updateDoc(reference: DocumentReference, data: UpdateData): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to update. | +| data | [UpdateData](./firestore_.md#updatedata)<T> | An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document. | + +Returns: + +Promise<void> + +A `Promise` resolved once the data has been successfully written to the backend (note that it won't resolve while you're offline). + +## updateDoc() + +Updates fields in the document referred to by the specified `DocumentReference` The update will fail if applied to a document that does not exist. + +Nested fields can be updated by providing dot-separated field path strings or by providing `FieldPath` objects. + +Signature: + +```typescript +export declare function updateDoc(reference: DocumentReference, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to the document to update. | +| field | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The first field to update. | +| value | unknown | The first value. | +| moreFieldsAndValues | unknown\[\] | Additional key value pairs. | + +Returns: + +Promise<void> + +A `Promise` resolved once the data has been successfully written to the backend (note that it won't resolve while you're offline). + +## endAt() + +Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided document (inclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. + +Signature: + +```typescript +export declare function endAt(snapshot: DocumentSnapshot): QueryEndAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| snapshot | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to end at. | + +Returns: + +[QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) + +A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` + +## endBefore() + +Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. + +Signature: + +```typescript +export declare function endBefore(snapshot: DocumentSnapshot): QueryEndAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| snapshot | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to end before. | + +Returns: + +[QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) + +A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` + +## startAfter() + +Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. + +Signature: + +```typescript +export declare function startAfter(snapshot: DocumentSnapshot): QueryStartAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| snapshot | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to start after. | + +Returns: + +[QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) + +A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()` + +## startAt() + +Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the `orderBy` of this query. + +Signature: + +```typescript +export declare function startAt(snapshot: DocumentSnapshot): QueryStartAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| snapshot | [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to start at. | + +Returns: + +[QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) + +A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()`. + +## CACHE\_SIZE\_UNLIMITED + +Constant used to indicate the LRU garbage collection should be disabled. Set this value as the `cacheSizeBytes` on the settings passed to the [Firestore](./firestore_.firestore.md#firestore_class) instance. + +Signature: + +```typescript +CACHE_SIZE_UNLIMITED = -1 +``` + +## AddPrefixToKeys + +Returns a new map where every key is prefixed with the outer key appended to a dot. + +Signature: + +```typescript +export declare type AddPrefixToKeys> = { + [K in keyof T & string as `${Prefix}.${K}`]+?: T[K]; +}; +``` + +## AggregateFieldType + +The union of all `AggregateField` types that are supported by Firestore. + +Signature: + +```typescript +export declare type AggregateFieldType = AggregateField; +``` + +## AggregateSpecData + +A type whose keys are taken from an `AggregateSpec`, and whose values are the result of the aggregation performed by the corresponding `AggregateField` from the input `AggregateSpec`. + +Signature: + +```typescript +export declare type AggregateSpecData = { + [P in keyof T]: T[P] extends AggregateField ? U : never; +}; +``` + +## ChildUpdateFields + +Helper for calculating the nested fields for a given type T1. This is needed to distribute union types such as `undefined | {...}` (happens for optional props) or `{a: A} | {b: B}`. + +In this use case, `V` is used to distribute the union types of `T[K]` on `Record`, since `T[K]` is evaluated as an expression and not distributed. + +See https://www.typescriptlang.org/docs/handbook/advanced-types.html\#distributive-conditional-types + +Signature: + +```typescript +export declare type ChildUpdateFields = V extends Record ? AddPrefixToKeys> : never; +``` + +## DocumentChangeType + +The type of a `DocumentChange` may be 'added', 'removed', or 'modified'. + +Signature: + +```typescript +export declare type DocumentChangeType = 'added' | 'removed' | 'modified'; +``` + +## FirestoreErrorCode + +The set of Firestore status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.md + +Possible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (e.g. an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation. + +Signature: + +```typescript +export declare type FirestoreErrorCode = 'cancelled' | 'unknown' | 'invalid-argument' | 'deadline-exceeded' | 'not-found' | 'already-exists' | 'permission-denied' | 'resource-exhausted' | 'failed-precondition' | 'aborted' | 'out-of-range' | 'unimplemented' | 'internal' | 'unavailable' | 'data-loss' | 'unauthenticated'; +``` + +## NestedUpdateFields + +For each field (e.g. 'bar'), find all nested keys (e.g. {'bar.baz': T1, 'bar.qux': T2}). Intersect them together to make a single map containing all possible keys that are all marked as optional + +Signature: + +```typescript +export declare type NestedUpdateFields> = UnionToIntersection<{ + [K in keyof T & string]: ChildUpdateFields; +}[keyof T & string]>; +``` + +## OrderByDirection + +The direction of a [orderBy()](./firestore_.md#orderby) clause is specified as 'desc' or 'asc' (descending or ascending). + +Signature: + +```typescript +export declare type OrderByDirection = 'desc' | 'asc'; +``` + +## PartialWithFieldValue + +Similar to Typescript's `Partial`, but allows nested fields to be omitted and FieldValues to be passed in as property values. + +Signature: + +```typescript +export declare type PartialWithFieldValue = Partial | (T extends Primitive ? T : T extends {} ? { + [K in keyof T]?: PartialWithFieldValue | FieldValue; +} : never); +``` + +## Primitive + +Primitive types. + +Signature: + +```typescript +export declare type Primitive = string | number | boolean | undefined | null; +``` + +## QueryConstraintType + +Describes the different query constraints available in this SDK. + +Signature: + +```typescript +export declare type QueryConstraintType = 'where' | 'orderBy' | 'limit' | 'limitToLast' | 'startAt' | 'startAfter' | 'endAt' | 'endBefore'; +``` + +## QueryNonFilterConstraint + +`QueryNonFilterConstraint` is a helper union type that represents QueryConstraints which are used to narrow or order the set of documents, but that do not explicitly filter on a document field. `QueryNonFilterConstraint`s are created by invoking [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains the `QueryConstraint`. + +Signature: + +```typescript +export declare type QueryNonFilterConstraint = QueryOrderByConstraint | QueryLimitConstraint | QueryStartAtConstraint | QueryEndAtConstraint; +``` + +## SetOptions + +An options object that configures the behavior of [setDoc()](./firestore_lite.md#setdoc), and calls. These calls can be configured to perform granular merges instead of overwriting the target documents in their entirety by providing a `SetOptions` with `merge: true`. + +Signature: + +```typescript +export declare type SetOptions = { + readonly merge?: boolean; +} | { + readonly mergeFields?: Array; +}; +``` + +## 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. + +Signature: + +```typescript +export declare type TaskState = 'Error' | 'Running' | 'Success'; +``` + +## UnionToIntersection + +Given a union type `U = T1 | T2 | ...`, returns an intersected type `(T1 & T2 & ...)`. + +Uses distributive conditional types and inference from conditional types. This works because multiple candidates for the same type variable in contra-variant positions causes an intersection type to be inferred. https://www.typescriptlang.org/docs/handbook/advanced-types.html\#type-inference-in-conditional-types https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection-type + +Signature: + +```typescript +export declare type UnionToIntersection = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never; +``` + +## UpdateData + +Update data (for use with [updateDoc()](./firestore_.md#updatedoc)) that consists of field paths (e.g. 'foo' or 'foo.baz') mapped to values. Fields that contain dots reference nested fields within the document. FieldValues can be passed in as property values. + +Signature: + +```typescript +export declare type UpdateData = T extends Primitive ? T : T extends {} ? { + [K in keyof T]?: UpdateData | FieldValue; +} & NestedUpdateFields : Partial; +``` + +## WhereFilterOp + +Filter conditions in a [where()](./firestore_.md#where) clause are specified using the strings '&lt;', '&lt;=', '==', '!=', '&gt;=', '&gt;', 'array-contains', 'in', 'array-contains-any', and 'not-in'. + +Signature: + +```typescript +export declare type WhereFilterOp = '<' | '<=' | '==' | '!=' | '>=' | '>' | 'array-contains' | 'in' | 'array-contains-any' | 'not-in'; +``` + +## WithFieldValue + +Allows FieldValues to be passed in as a property value while maintaining type safety. + +Signature: + +```typescript +export declare type WithFieldValue = T | (T extends Primitive ? T : T extends {} ? { + [K in keyof T]: WithFieldValue | FieldValue; +} : never); +``` diff --git a/docs-devsite/firestore_.persistencesettings.md b/docs-devsite/firestore_.persistencesettings.md new file mode 100644 index 00000000000..c84cde1ed13 --- /dev/null +++ b/docs-devsite/firestore_.persistencesettings.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# PersistenceSettings interface +Settings that can be passed to `enableIndexedDbPersistence()` to configure Firestore persistence. + +Signature: + +```typescript +export declare interface PersistenceSettings +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [forceOwnership](./firestore_.persistencesettings.md#persistencesettingsforceownership) | boolean | Whether to force enable persistence for the client. This cannot be used with multi-tab synchronization and is primarily intended for use with Web Workers. Setting this to true will enable persistence, but cause other tabs using persistence to fail. | + +## PersistenceSettings.forceOwnership + +Whether to force enable persistence for the client. This cannot be used with multi-tab synchronization and is primarily intended for use with Web Workers. Setting this to `true` will enable persistence, but cause other tabs using persistence to fail. + +Signature: + +```typescript +forceOwnership?: boolean; +``` diff --git a/docs-devsite/firestore_.query.md b/docs-devsite/firestore_.query.md new file mode 100644 index 00000000000..1961c2cc5f3 --- /dev/null +++ b/docs-devsite/firestore_.query.md @@ -0,0 +1,125 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Query class +A `Query` refers to a query which you can read or listen to. You can also construct refined `Query` objects by adding filters and ordering. + +Signature: + +```typescript +export declare class Query +``` + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)()](./firestore_.query.md#queryconstructor) | | Constructs a new instance of the Query class | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [converter](./firestore_.query.md#queryconverter) | | [FirestoreDataConverter](./firestore_.firestoredataconverter.md#firestoredataconverter_interface)<T> \| null | If provided, the FirestoreDataConverter associated with this instance. | +| [firestore](./firestore_.query.md#queryfirestore) | | [Firestore](./firestore_.firestore.md#firestore_class) | The Firestore instance for the Firestore database (useful for performing transactions, etc.). | +| [type](./firestore_.query.md#querytype) | | 'query' \| 'collection' | The type of this Firestore reference. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [withConverter(converter)](./firestore_.query.md#querywithconverter) | | Removes the current converter. | +| [withConverter(converter)](./firestore_.query.md#querywithconverter) | | Applies a custom data converter to this query, allowing you to use your own custom model objects with Firestore. When you call [getDocs()](./firestore_.md#getdocs) with the returned query, the provided converter will convert between Firestore data and your custom type U. | + +## Query.(constructor) + +Constructs a new instance of the `Query` class + +Signature: + +```typescript +protected constructor(); +``` + +## Query.converter + +If provided, the `FirestoreDataConverter` associated with this instance. + +Signature: + +```typescript +readonly converter: FirestoreDataConverter | null; +``` + +## Query.firestore + +The `Firestore` instance for the Firestore database (useful for performing transactions, etc.). + +Signature: + +```typescript +readonly firestore: Firestore; +``` + +## Query.type + +The type of this Firestore reference. + +Signature: + +```typescript +readonly type: 'query' | 'collection'; +``` + +## Query.withConverter() + +Removes the current converter. + +Signature: + +```typescript +withConverter(converter: null): Query; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| converter | null | null removes the current converter. | + +Returns: + +[Query](./firestore_.query.md#query_class)<[DocumentData](./firestore_.documentdata.md#documentdata_interface)> + +A `Query` that does not use a converter. + +## Query.withConverter() + +Applies a custom data converter to this query, allowing you to use your own custom model objects with Firestore. When you call [getDocs()](./firestore_.md#getdocs) with the returned query, the provided converter will convert between Firestore data and your custom type `U`. + +Signature: + +```typescript +withConverter(converter: FirestoreDataConverter): Query; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| converter | [FirestoreDataConverter](./firestore_.firestoredataconverter.md#firestoredataconverter_interface)<U> | Converts objects to and from Firestore. | + +Returns: + +[Query](./firestore_.query.md#query_class)<U> + +A `Query` that uses the provided converter. + diff --git a/docs-devsite/firestore_.queryconstraint.md b/docs-devsite/firestore_.queryconstraint.md new file mode 100644 index 00000000000..77ebddf1c65 --- /dev/null +++ b/docs-devsite/firestore_.queryconstraint.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryConstraint class +A `QueryConstraint` is used to narrow the set of documents returned by a Firestore query. `QueryConstraint`s are created by invoking [where()](./firestore_.md#where), [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit), [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryConstraint`. + +Signature: + +```typescript +export declare abstract class QueryConstraint +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_.queryconstraint.md#queryconstrainttype) | | [QueryConstraintType](./firestore_.md#queryconstrainttype) | The type of this query constraint | + +## QueryConstraint.type + +The type of this query constraint + +Signature: + +```typescript +abstract readonly type: QueryConstraintType; +``` diff --git a/docs-devsite/firestore_.querydocumentsnapshot.md b/docs-devsite/firestore_.querydocumentsnapshot.md new file mode 100644 index 00000000000..0755a11915f --- /dev/null +++ b/docs-devsite/firestore_.querydocumentsnapshot.md @@ -0,0 +1,54 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryDocumentSnapshot class +A `QueryDocumentSnapshot` contains data read from a document in your Firestore database as part of a query. The document is guaranteed to exist and its data can be extracted with `.data()` or `.get()` to get a specific field. + +A `QueryDocumentSnapshot` offers the same API surface as a `DocumentSnapshot`. Since query results contain only existing documents, the `exists` property will always be true and `data()` will never return 'undefined'. + +Signature: + +```typescript +export declare class QueryDocumentSnapshot extends DocumentSnapshot +``` +Extends: [DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T> + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [data(options)](./firestore_.querydocumentsnapshot.md#querydocumentsnapshotdata) | | Retrieves all fields in the document as an Object.By default, serverTimestamp() values that have not yet been set to their final value will be returned as null. You can override this by passing an options object. | + +## QueryDocumentSnapshot.data() + +Retrieves all fields in the document as an `Object`. + +By default, `serverTimestamp()` values that have not yet been set to their final value will be returned as `null`. You can override this by passing an options object. + +Signature: + +```typescript +/** @override */ +data(options?: SnapshotOptions): T; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| options | [SnapshotOptions](./firestore_.snapshotoptions.md#snapshotoptions_interface) | An options object to configure how data is retrieved from the snapshot (for example the desired behavior for server timestamps that have not yet been set to their final value). | + +Returns: + +T + +An `Object` containing all fields in the document. + diff --git a/docs-devsite/firestore_.queryendatconstraint.md b/docs-devsite/firestore_.queryendatconstraint.md new file mode 100644 index 00000000000..44dcddab71b --- /dev/null +++ b/docs-devsite/firestore_.queryendatconstraint.md @@ -0,0 +1,36 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryEndAtConstraint class +A `QueryEndAtConstraint` is used to exclude documents from the end of a result set returned by a Firestore query. `QueryEndAtConstraint`s are created by invoking [endAt()](./firestore_.md#endat) or [endBefore()](./firestore_.md#endbefore) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryEndAtConstraint`. + +Signature: + +```typescript +export declare class QueryEndAtConstraint extends QueryConstraint +``` +Extends: [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_.queryendatconstraint.md#queryendatconstrainttype) | | 'endBefore' \| 'endAt' | The type of this query constraint | + +## QueryEndAtConstraint.type + +The type of this query constraint + +Signature: + +```typescript +readonly type: 'endBefore' | 'endAt'; +``` diff --git a/docs-devsite/firestore_.queryfieldfilterconstraint.md b/docs-devsite/firestore_.queryfieldfilterconstraint.md new file mode 100644 index 00000000000..18710b6aa99 --- /dev/null +++ b/docs-devsite/firestore_.queryfieldfilterconstraint.md @@ -0,0 +1,36 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryFieldFilterConstraint class +A `QueryFieldFilterConstraint` is used to narrow the set of documents returned by a Firestore query by filtering on one or more document fields. `QueryFieldFilterConstraint`s are created by invoking [where()](./firestore_.md#where) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryFieldFilterConstraint`. + +Signature: + +```typescript +export declare class QueryFieldFilterConstraint extends QueryConstraint +``` +Extends: [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstrainttype) | | (not declared) | The type of this query constraint | + +## QueryFieldFilterConstraint.type + +The type of this query constraint + +Signature: + +```typescript +readonly type = "where"; +``` diff --git a/docs-devsite/firestore_.querylimitconstraint.md b/docs-devsite/firestore_.querylimitconstraint.md new file mode 100644 index 00000000000..72b06d61073 --- /dev/null +++ b/docs-devsite/firestore_.querylimitconstraint.md @@ -0,0 +1,36 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryLimitConstraint class +A `QueryLimitConstraint` is used to limit the number of documents returned by a Firestore query. `QueryLimitConstraint`s are created by invoking [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryLimitConstraint`. + +Signature: + +```typescript +export declare class QueryLimitConstraint extends QueryConstraint +``` +Extends: [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_.querylimitconstraint.md#querylimitconstrainttype) | | 'limit' \| 'limitToLast' | The type of this query constraint | + +## QueryLimitConstraint.type + +The type of this query constraint + +Signature: + +```typescript +readonly type: 'limit' | 'limitToLast'; +``` diff --git a/docs-devsite/firestore_.queryorderbyconstraint.md b/docs-devsite/firestore_.queryorderbyconstraint.md new file mode 100644 index 00000000000..6f24ac985dd --- /dev/null +++ b/docs-devsite/firestore_.queryorderbyconstraint.md @@ -0,0 +1,38 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryOrderByConstraint class +A `QueryOrderByConstraint` is used to sort the set of documents returned by a Firestore query. `QueryOrderByConstraint`s are created by invoking [orderBy()](./firestore_.md#orderby) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryOrderByConstraint`. + +Note: Documents that do not contain the orderBy field will not be present in the query result. + +Signature: + +```typescript +export declare class QueryOrderByConstraint extends QueryConstraint +``` +Extends: [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_.queryorderbyconstraint.md#queryorderbyconstrainttype) | | (not declared) | The type of this query constraint | + +## QueryOrderByConstraint.type + +The type of this query constraint + +Signature: + +```typescript +readonly type = "orderBy"; +``` diff --git a/docs-devsite/firestore_.querysnapshot.md b/docs-devsite/firestore_.querysnapshot.md new file mode 100644 index 00000000000..0abb869c003 --- /dev/null +++ b/docs-devsite/firestore_.querysnapshot.md @@ -0,0 +1,128 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QuerySnapshot class +A `QuerySnapshot` contains zero or more `DocumentSnapshot` objects representing the results of a query. The documents can be accessed as an array via the `docs` property or enumerated using the `forEach` method. The number of documents can be determined via the `empty` and `size` properties. + +Signature: + +```typescript +export declare class QuerySnapshot +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [docs](./firestore_.querysnapshot.md#querysnapshotdocs) | | Array<[QueryDocumentSnapshot](./firestore_.querydocumentsnapshot.md#querydocumentsnapshot_class)<T>> | An array of all the documents in the QuerySnapshot. | +| [empty](./firestore_.querysnapshot.md#querysnapshotempty) | | boolean | True if there are no documents in the QuerySnapshot. | +| [metadata](./firestore_.querysnapshot.md#querysnapshotmetadata) | | [SnapshotMetadata](./firestore_.snapshotmetadata.md#snapshotmetadata_class) | Metadata about this snapshot, concerning its source and if it has local modifications. | +| [query](./firestore_.querysnapshot.md#querysnapshotquery) | | [Query](./firestore_.query.md#query_class)<T> | The query on which you called get or onSnapshot in order to get this QuerySnapshot. | +| [size](./firestore_.querysnapshot.md#querysnapshotsize) | | number | The number of documents in the QuerySnapshot. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [docChanges(options)](./firestore_.querysnapshot.md#querysnapshotdocchanges) | | Returns an array of the documents changes since the last snapshot. If this is the first snapshot, all documents will be in the list as 'added' changes. | +| [forEach(callback, thisArg)](./firestore_.querysnapshot.md#querysnapshotforeach) | | Enumerates all of the documents in the QuerySnapshot. | + +## QuerySnapshot.docs + +An array of all the documents in the `QuerySnapshot`. + +Signature: + +```typescript +get docs(): Array>; +``` + +## QuerySnapshot.empty + +True if there are no documents in the `QuerySnapshot`. + +Signature: + +```typescript +get empty(): boolean; +``` + +## QuerySnapshot.metadata + +Metadata about this snapshot, concerning its source and if it has local modifications. + +Signature: + +```typescript +readonly metadata: SnapshotMetadata; +``` + +## QuerySnapshot.query + +The query on which you called `get` or `onSnapshot` in order to get this `QuerySnapshot`. + +Signature: + +```typescript +readonly query: Query; +``` + +## QuerySnapshot.size + +The number of documents in the `QuerySnapshot`. + +Signature: + +```typescript +get size(): number; +``` + +## QuerySnapshot.docChanges() + +Returns an array of the documents changes since the last snapshot. If this is the first snapshot, all documents will be in the list as 'added' changes. + +Signature: + +```typescript +docChanges(options?: SnapshotListenOptions): Array>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| options | [SnapshotListenOptions](./firestore_.snapshotlistenoptions.md#snapshotlistenoptions_interface) | SnapshotListenOptions that control whether metadata-only changes (i.e. only DocumentSnapshot.metadata changed) should trigger snapshot events. | + +Returns: + +Array<[DocumentChange](./firestore_.documentchange.md#documentchange_interface)<T>> + +## QuerySnapshot.forEach() + +Enumerates all of the documents in the `QuerySnapshot`. + +Signature: + +```typescript +forEach(callback: (result: QueryDocumentSnapshot) => void, thisArg?: unknown): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| callback | (result: [QueryDocumentSnapshot](./firestore_.querydocumentsnapshot.md#querydocumentsnapshot_class)<T>) => void | A callback to be called with a QueryDocumentSnapshot for each document in the snapshot. | +| thisArg | unknown | The this binding for the callback. | + +Returns: + +void + diff --git a/docs-devsite/firestore_.querystartatconstraint.md b/docs-devsite/firestore_.querystartatconstraint.md new file mode 100644 index 00000000000..edad47f66ee --- /dev/null +++ b/docs-devsite/firestore_.querystartatconstraint.md @@ -0,0 +1,36 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryStartAtConstraint class +A `QueryStartAtConstraint` is used to exclude documents from the start of a result set returned by a Firestore query. `QueryStartAtConstraint`s are created by invoking [startAt()](./firestore_.md#startat) or [startAfter()](./firestore_.md#startafter) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryStartAtConstraint`. + +Signature: + +```typescript +export declare class QueryStartAtConstraint extends QueryConstraint +``` +Extends: [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_.querystartatconstraint.md#querystartatconstrainttype) | | 'startAt' \| 'startAfter' | The type of this query constraint | + +## QueryStartAtConstraint.type + +The type of this query constraint + +Signature: + +```typescript +readonly type: 'startAt' | 'startAfter'; +``` diff --git a/docs-devsite/firestore_.snapshotlistenoptions.md b/docs-devsite/firestore_.snapshotlistenoptions.md new file mode 100644 index 00000000000..dba8308fc02 --- /dev/null +++ b/docs-devsite/firestore_.snapshotlistenoptions.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# SnapshotListenOptions interface +An options object that can be passed to [onSnapshot()](./firestore_.md#onsnapshot) and [QuerySnapshot.docChanges()](./firestore_.querysnapshot.md#querysnapshotdocchanges) to control which types of changes to include in the result set. + +Signature: + +```typescript +export declare interface SnapshotListenOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [includeMetadataChanges](./firestore_.snapshotlistenoptions.md#snapshotlistenoptionsincludemetadatachanges) | boolean | Include a change even if only the metadata of the query or of a document changed. Default is false. | + +## SnapshotListenOptions.includeMetadataChanges + +Include a change even if only the metadata of the query or of a document changed. Default is false. + +Signature: + +```typescript +readonly includeMetadataChanges?: boolean; +``` diff --git a/docs-devsite/firestore_.snapshotmetadata.md b/docs-devsite/firestore_.snapshotmetadata.md new file mode 100644 index 00000000000..6f062ed1c92 --- /dev/null +++ b/docs-devsite/firestore_.snapshotmetadata.md @@ -0,0 +1,75 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# SnapshotMetadata class +Metadata about a snapshot, describing the state of the snapshot. + +Signature: + +```typescript +export declare class SnapshotMetadata +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [fromCache](./firestore_.snapshotmetadata.md#snapshotmetadatafromcache) | | boolean | True if the snapshot was created from cached data rather than guaranteed up-to-date server data. If your listener has opted into metadata updates (via SnapshotListenOptions) you will receive another snapshot with fromCache set to false once the client has received up-to-date data from the backend. | +| [hasPendingWrites](./firestore_.snapshotmetadata.md#snapshotmetadatahaspendingwrites) | | boolean | True if the snapshot contains the result of local writes (for example set() or update() calls) that have not yet been committed to the backend. If your listener has opted into metadata updates (via SnapshotListenOptions) you will receive another snapshot with hasPendingWrites equal to false once the writes have been committed to the backend. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [isEqual(other)](./firestore_.snapshotmetadata.md#snapshotmetadataisequal) | | Returns true if this SnapshotMetadata is equal to the provided one. | + +## SnapshotMetadata.fromCache + +True if the snapshot was created from cached data rather than guaranteed up-to-date server data. If your listener has opted into metadata updates (via `SnapshotListenOptions`) you will receive another snapshot with `fromCache` set to false once the client has received up-to-date data from the backend. + +Signature: + +```typescript +readonly fromCache: boolean; +``` + +## SnapshotMetadata.hasPendingWrites + +True if the snapshot contains the result of local writes (for example `set()` or `update()` calls) that have not yet been committed to the backend. If your listener has opted into metadata updates (via `SnapshotListenOptions`) you will receive another snapshot with `hasPendingWrites` equal to false once the writes have been committed to the backend. + +Signature: + +```typescript +readonly hasPendingWrites: boolean; +``` + +## SnapshotMetadata.isEqual() + +Returns true if this `SnapshotMetadata` is equal to the provided one. + +Signature: + +```typescript +isEqual(other: SnapshotMetadata): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| other | [SnapshotMetadata](./firestore_.snapshotmetadata.md#snapshotmetadata_class) | The SnapshotMetadata to compare against. | + +Returns: + +boolean + +true if this `SnapshotMetadata` is equal to the provided one. + diff --git a/docs-devsite/firestore_.snapshotoptions.md b/docs-devsite/firestore_.snapshotoptions.md new file mode 100644 index 00000000000..e7ccd715552 --- /dev/null +++ b/docs-devsite/firestore_.snapshotoptions.md @@ -0,0 +1,41 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# SnapshotOptions interface +Options that configure how data is retrieved from a `DocumentSnapshot` (for example the desired behavior for server timestamps that have not yet been set to their final value). + +Signature: + +```typescript +export declare interface SnapshotOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [serverTimestamps](./firestore_.snapshotoptions.md#snapshotoptionsservertimestamps) | 'estimate' \| 'previous' \| 'none' | If set, controls the return value for server timestamps that have not yet been set to their final value.By specifying 'estimate', pending server timestamps return an estimate based on the local clock. This estimate will differ from the final value and cause these values to change once the server result becomes available.By specifying 'previous', pending timestamps will be ignored and return their previous value instead.If omitted or set to 'none', null will be returned by default until the server value becomes available. | + +## SnapshotOptions.serverTimestamps + +If set, controls the return value for server timestamps that have not yet been set to their final value. + +By specifying 'estimate', pending server timestamps return an estimate based on the local clock. This estimate will differ from the final value and cause these values to change once the server result becomes available. + +By specifying 'previous', pending timestamps will be ignored and return their previous value instead. + +If omitted or set to 'none', `null` will be returned by default until the server value becomes available. + +Signature: + +```typescript +readonly serverTimestamps?: 'estimate' | 'previous' | 'none'; +``` diff --git a/docs-devsite/firestore_.timestamp.md b/docs-devsite/firestore_.timestamp.md new file mode 100644 index 00000000000..ef75f07fdd5 --- /dev/null +++ b/docs-devsite/firestore_.timestamp.md @@ -0,0 +1,243 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Timestamp class +A `Timestamp` represents a point in time independent of any time zone or calendar, represented as seconds and fractions of seconds at nanosecond resolution in UTC Epoch time. + +It is encoded using the Proleptic Gregorian Calendar which extends the Gregorian calendar backwards to year one. It is encoded assuming all minutes are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. + +For examples and further specifications, refer to the [Timestamp definition](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto). + +Signature: + +```typescript +export declare class Timestamp +``` + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(seconds, nanoseconds)](./firestore_.timestamp.md#timestampconstructor) | | Creates a new timestamp. | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [nanoseconds](./firestore_.timestamp.md#timestampnanoseconds) | | number | The fractions of a second at nanosecond resolution.\* | +| [seconds](./firestore_.timestamp.md#timestampseconds) | | number | The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [fromDate(date)](./firestore_.timestamp.md#timestampfromdate) | static | Creates a new timestamp from the given date. | +| [fromMillis(milliseconds)](./firestore_.timestamp.md#timestampfrommillis) | static | Creates a new timestamp from the given number of milliseconds. | +| [isEqual(other)](./firestore_.timestamp.md#timestampisequal) | | Returns true if this Timestamp is equal to the provided one. | +| [now()](./firestore_.timestamp.md#timestampnow) | static | Creates a new timestamp with the current date, with millisecond precision. | +| [toDate()](./firestore_.timestamp.md#timestamptodate) | | Converts a Timestamp to a JavaScript Date object. This conversion causes a loss of precision since Date objects only support millisecond precision. | +| [toJSON()](./firestore_.timestamp.md#timestamptojson) | | Returns a JSON-serializable representation of this Timestamp. | +| [toMillis()](./firestore_.timestamp.md#timestamptomillis) | | Converts a Timestamp to a numeric timestamp (in milliseconds since epoch). This operation causes a loss of precision. | +| [toString()](./firestore_.timestamp.md#timestamptostring) | | Returns a textual representation of this Timestamp. | +| [valueOf()](./firestore_.timestamp.md#timestampvalueof) | | Converts this object to a primitive string, which allows Timestamp objects to be compared using the >, <=, >= and > operators. | + +## Timestamp.(constructor) + +Creates a new timestamp. + +Signature: + +```typescript +constructor( + seconds: number, + nanoseconds: number); +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| seconds | number | The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive. | +| nanoseconds | number | The non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanoseconds values that count forward in time. Must be from 0 to 999,999,999 inclusive. | + +## Timestamp.nanoseconds + +The fractions of a second at nanosecond resolution.\* + +Signature: + +```typescript +readonly nanoseconds: number; +``` + +## Timestamp.seconds + +The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. + +Signature: + +```typescript +readonly seconds: number; +``` + +## Timestamp.fromDate() + +Creates a new timestamp from the given date. + +Signature: + +```typescript +static fromDate(date: Date): Timestamp; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| date | Date | The date to initialize the Timestamp from. | + +Returns: + +[Timestamp](./firestore_.timestamp.md#timestamp_class) + +A new `Timestamp` representing the same point in time as the given date. + +## Timestamp.fromMillis() + +Creates a new timestamp from the given number of milliseconds. + +Signature: + +```typescript +static fromMillis(milliseconds: number): Timestamp; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| milliseconds | number | Number of milliseconds since Unix epoch 1970-01-01T00:00:00Z. | + +Returns: + +[Timestamp](./firestore_.timestamp.md#timestamp_class) + +A new `Timestamp` representing the same point in time as the given number of milliseconds. + +## Timestamp.isEqual() + +Returns true if this `Timestamp` is equal to the provided one. + +Signature: + +```typescript +isEqual(other: Timestamp): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| other | [Timestamp](./firestore_.timestamp.md#timestamp_class) | The Timestamp to compare against. | + +Returns: + +boolean + +true if this `Timestamp` is equal to the provided one. + +## Timestamp.now() + +Creates a new timestamp with the current date, with millisecond precision. + +Signature: + +```typescript +static now(): Timestamp; +``` +Returns: + +[Timestamp](./firestore_.timestamp.md#timestamp_class) + +a new timestamp representing the current date. + +## Timestamp.toDate() + +Converts a `Timestamp` to a JavaScript `Date` object. This conversion causes a loss of precision since `Date` objects only support millisecond precision. + +Signature: + +```typescript +toDate(): Date; +``` +Returns: + +Date + +JavaScript `Date` object representing the same point in time as this `Timestamp`, with millisecond precision. + +## Timestamp.toJSON() + +Returns a JSON-serializable representation of this `Timestamp`. + +Signature: + +```typescript +toJSON(): { + seconds: number; + nanoseconds: number; + }; +``` +Returns: + +{ seconds: number; nanoseconds: number; } + +## Timestamp.toMillis() + +Converts a `Timestamp` to a numeric timestamp (in milliseconds since epoch). This operation causes a loss of precision. + +Signature: + +```typescript +toMillis(): number; +``` +Returns: + +number + +The point in time corresponding to this timestamp, represented as the number of milliseconds since Unix epoch 1970-01-01T00:00:00Z. + +## Timestamp.toString() + +Returns a textual representation of this `Timestamp`. + +Signature: + +```typescript +toString(): string; +``` +Returns: + +string + +## Timestamp.valueOf() + +Converts this object to a primitive string, which allows `Timestamp` objects to be compared using the `>`, `<=`, `>=` and `>` operators. + +Signature: + +```typescript +valueOf(): string; +``` +Returns: + +string + diff --git a/docs-devsite/firestore_.transaction.md b/docs-devsite/firestore_.transaction.md new file mode 100644 index 00000000000..24f0690bea4 --- /dev/null +++ b/docs-devsite/firestore_.transaction.md @@ -0,0 +1,190 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Transaction class +A reference to a transaction. + +The `Transaction` object passed to a transaction's `updateFunction` provides the methods to read and write data within the transaction context. See [runTransaction()](./firestore_.md#runtransaction). + +Signature: + +```typescript +export declare class Transaction +``` + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [delete(documentRef)](./firestore_.transaction.md#transactiondelete) | | Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). | +| [get(documentRef)](./firestore_.transaction.md#transactionget) | | Reads the document referenced by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). | +| [set(documentRef, data)](./firestore_.transaction.md#transactionset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. | +| [set(documentRef, data, options)](./firestore_.transaction.md#transactionset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document. | +| [update(documentRef, data)](./firestore_.transaction.md#transactionupdate) | | Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. | +| [update(documentRef, field, value, moreFieldsAndValues)](./firestore_.transaction.md#transactionupdate) | | Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist.Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects. | + +## Transaction.delete() + +Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). + +Signature: + +```typescript +delete(documentRef: DocumentReference): this; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to the document to be deleted. | + +Returns: + +this + +This `Transaction` instance. Used for chaining method calls. + +## Transaction.get() + +Reads the document referenced by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). + +Signature: + +```typescript +get(documentRef: DocumentReference): Promise>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be read. | + +Returns: + +Promise<[DocumentSnapshot](./firestore_.documentsnapshot.md#documentsnapshot_class)<T>> + +A `DocumentSnapshot` with the read data. + +## Transaction.set() + +Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. + +Signature: + +```typescript +set(documentRef: DocumentReference, data: WithFieldValue): this; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | +| data | [WithFieldValue](./firestore_.md#withfieldvalue)<T> | An object of the fields and values for the document. | + +Returns: + +this + +This `Transaction` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not a valid Firestore document. + +## Transaction.set() + +Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. + +Signature: + +```typescript +set(documentRef: DocumentReference, data: PartialWithFieldValue, options: SetOptions): this; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | +| data | [PartialWithFieldValue](./firestore_.md#partialwithfieldvalue)<T> | An object of the fields and values for the document. | +| options | [SetOptions](./firestore_.md#setoptions) | An object to configure the set behavior. | + +Returns: + +this + +This `Transaction` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not a valid Firestore document. + +## Transaction.update() + +Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. + +Signature: + +```typescript +update(documentRef: DocumentReference, data: UpdateData): this; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be updated. | +| data | [UpdateData](./firestore_.md#updatedata)<T> | An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document. | + +Returns: + +this + +This `Transaction` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not valid Firestore data. + +## Transaction.update() + +Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. + +Nested fields can be updated by providing dot-separated field path strings or by providing `FieldPath` objects. + +Signature: + +```typescript +update(documentRef: DocumentReference, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): this; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to the document to be updated. | +| field | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The first field to update. | +| value | unknown | The first value. | +| moreFieldsAndValues | unknown\[\] | Additional key/value pairs. | + +Returns: + +this + +This `Transaction` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not valid Firestore data. + diff --git a/docs-devsite/firestore_.transactionoptions.md b/docs-devsite/firestore_.transactionoptions.md new file mode 100644 index 00000000000..1e7a5aedd28 --- /dev/null +++ b/docs-devsite/firestore_.transactionoptions.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# TransactionOptions interface +Options to customize transaction behavior. + +Signature: + +```typescript +export declare interface TransactionOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [maxAttempts](./firestore_.transactionoptions.md#transactionoptionsmaxattempts) | number | Maximum number of attempts to commit, after which transaction fails. Default is 5. | + +## TransactionOptions.maxAttempts + +Maximum number of attempts to commit, after which transaction fails. Default is 5. + +Signature: + +```typescript +readonly maxAttempts?: number; +``` diff --git a/docs-devsite/firestore_.unsubscribe.md b/docs-devsite/firestore_.unsubscribe.md new file mode 100644 index 00000000000..8bafb4f9ee8 --- /dev/null +++ b/docs-devsite/firestore_.unsubscribe.md @@ -0,0 +1,19 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Unsubscribe interface +A function returned by `onSnapshot()` that removes the listener when invoked. + +Signature: + +```typescript +export declare interface Unsubscribe +``` diff --git a/docs-devsite/firestore_.writebatch.md b/docs-devsite/firestore_.writebatch.md new file mode 100644 index 00000000000..878cb66810a --- /dev/null +++ b/docs-devsite/firestore_.writebatch.md @@ -0,0 +1,181 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# WriteBatch class +A write batch, used to perform multiple writes as a single atomic unit. + +A `WriteBatch` object can be acquired by calling [writeBatch()](./firestore_.md#writebatch). It provides methods for adding writes to the write batch. None of the writes will be committed (or visible locally) until [WriteBatch.commit()](./firestore_.writebatch.md#writebatchcommit) is called. + +Signature: + +```typescript +export declare class WriteBatch +``` + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [commit()](./firestore_.writebatch.md#writebatchcommit) | | Commits all of the writes in this write batch as a single atomic unit.The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | +| [delete(documentRef)](./firestore_.writebatch.md#writebatchdelete) | | Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). | +| [set(documentRef, data)](./firestore_.writebatch.md#writebatchset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. | +| [set(documentRef, data, options)](./firestore_.writebatch.md#writebatchset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document. | +| [update(documentRef, data)](./firestore_.writebatch.md#writebatchupdate) | | Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. | +| [update(documentRef, field, value, moreFieldsAndValues)](./firestore_.writebatch.md#writebatchupdate) | | Updates fields in the document referred to by this [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist.Nested fields can be update by providing dot-separated field path strings or by providing FieldPath objects. | + +## WriteBatch.commit() + +Commits all of the writes in this write batch as a single atomic unit. + +The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. + +Signature: + +```typescript +commit(): Promise; +``` +Returns: + +Promise<void> + +A `Promise` resolved once all of the writes in the batch have been successfully written to the backend as an atomic unit (note that it won't resolve while you're offline). + +## WriteBatch.delete() + +Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). + +Signature: + +```typescript +delete(documentRef: DocumentReference): WriteBatch; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to the document to be deleted. | + +Returns: + +[WriteBatch](./firestore_.writebatch.md#writebatch_class) + +This `WriteBatch` instance. Used for chaining method calls. + +## WriteBatch.set() + +Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. + +Signature: + +```typescript +set(documentRef: DocumentReference, data: WithFieldValue): WriteBatch; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | +| data | [WithFieldValue](./firestore_.md#withfieldvalue)<T> | An object of the fields and values for the document. | + +Returns: + +[WriteBatch](./firestore_.writebatch.md#writebatch_class) + +This `WriteBatch` instance. Used for chaining method calls. + +## WriteBatch.set() + +Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. + +Signature: + +```typescript +set(documentRef: DocumentReference, data: PartialWithFieldValue, options: SetOptions): WriteBatch; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | +| data | [PartialWithFieldValue](./firestore_.md#partialwithfieldvalue)<T> | An object of the fields and values for the document. | +| options | [SetOptions](./firestore_.md#setoptions) | An object to configure the set behavior. | + +Returns: + +[WriteBatch](./firestore_.writebatch.md#writebatch_class) + +This `WriteBatch` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not a valid Firestore document. + +## WriteBatch.update() + +Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. + +Signature: + +```typescript +update(documentRef: DocumentReference, data: UpdateData): WriteBatch; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<T> | A reference to the document to be updated. | +| data | [UpdateData](./firestore_.md#updatedata)<T> | An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document. | + +Returns: + +[WriteBatch](./firestore_.writebatch.md#writebatch_class) + +This `WriteBatch` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not valid Firestore data. + +## WriteBatch.update() + +Updates fields in the document referred to by this [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. + +Nested fields can be update by providing dot-separated field path strings or by providing `FieldPath` objects. + +Signature: + +```typescript +update(documentRef: DocumentReference, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): WriteBatch; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_.documentreference.md#documentreference_class)<unknown> | A reference to the document to be updated. | +| field | string \| [FieldPath](./firestore_.fieldpath.md#fieldpath_class) | The first field to update. | +| value | unknown | The first value. | +| moreFieldsAndValues | unknown\[\] | Additional key value pairs. | + +Returns: + +[WriteBatch](./firestore_.writebatch.md#writebatch_class) + +This `WriteBatch` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not valid Firestore data. + diff --git a/docs-devsite/firestore_lite.aggregatefield.md b/docs-devsite/firestore_lite.aggregatefield.md new file mode 100644 index 00000000000..952b60c9d80 --- /dev/null +++ b/docs-devsite/firestore_lite.aggregatefield.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AggregateField class +Represents an aggregation that can be performed by Firestore. + +Signature: + +```typescript +export declare class AggregateField +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_lite.aggregatefield.md#aggregatefieldtype) | | string | A type string to uniquely identify instances of this class. | + +## AggregateField.type + +A type string to uniquely identify instances of this class. + +Signature: + +```typescript +type: string; +``` diff --git a/docs-devsite/firestore_lite.aggregatequerysnapshot.md b/docs-devsite/firestore_lite.aggregatequerysnapshot.md new file mode 100644 index 00000000000..4b5d3120ba3 --- /dev/null +++ b/docs-devsite/firestore_lite.aggregatequerysnapshot.md @@ -0,0 +1,70 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AggregateQuerySnapshot class +The results of executing an aggregation query. + +Signature: + +```typescript +export declare class AggregateQuerySnapshot +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [query](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshotquery) | | [Query](./firestore_lite.query.md#query_class)<unknown> | The underlying query over which the aggregations recorded in this AggregateQuerySnapshot were performed. | +| [type](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshottype) | | (not declared) | A type string to uniquely identify instances of this class. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [data()](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshotdata) | | Returns the results of the aggregations performed over the underlying query.The keys of the returned object will be the same as those of the AggregateSpec object specified to the aggregation method, and the values will be the corresponding aggregation result. | + +## AggregateQuerySnapshot.query + +The underlying query over which the aggregations recorded in this `AggregateQuerySnapshot` were performed. + +Signature: + +```typescript +readonly query: Query; +``` + +## AggregateQuerySnapshot.type + +A type string to uniquely identify instances of this class. + +Signature: + +```typescript +readonly type = "AggregateQuerySnapshot"; +``` + +## AggregateQuerySnapshot.data() + +Returns the results of the aggregations performed over the underlying query. + +The keys of the returned object will be the same as those of the `AggregateSpec` object specified to the aggregation method, and the values will be the corresponding aggregation result. + +Signature: + +```typescript +data(): AggregateSpecData; +``` +Returns: + +[AggregateSpecData](./firestore_lite.md#aggregatespecdata)<T> + +The results of the aggregations performed over the underlying query. + diff --git a/docs-devsite/firestore_lite.aggregatespec.md b/docs-devsite/firestore_lite.aggregatespec.md new file mode 100644 index 00000000000..be06b6941f3 --- /dev/null +++ b/docs-devsite/firestore_lite.aggregatespec.md @@ -0,0 +1,19 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# AggregateSpec interface +A type whose property values are all `AggregateField` objects. + +Signature: + +```typescript +export declare interface AggregateSpec +``` diff --git a/docs-devsite/firestore_lite.bytes.md b/docs-devsite/firestore_lite.bytes.md new file mode 100644 index 00000000000..8dec3bdd201 --- /dev/null +++ b/docs-devsite/firestore_lite.bytes.md @@ -0,0 +1,138 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Bytes class +An immutable object representing an array of bytes. + +Signature: + +```typescript +export declare class Bytes +``` + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [fromBase64String(base64)](./firestore_lite.bytes.md#bytesfrombase64string) | static | Creates a new Bytes object from the given Base64 string, converting it to bytes. | +| [fromUint8Array(array)](./firestore_lite.bytes.md#bytesfromuint8array) | static | Creates a new Bytes object from the given Uint8Array. | +| [isEqual(other)](./firestore_lite.bytes.md#bytesisequal) | | Returns true if this Bytes object is equal to the provided one. | +| [toBase64()](./firestore_lite.bytes.md#bytestobase64) | | Returns the underlying bytes as a Base64-encoded string. | +| [toString()](./firestore_lite.bytes.md#bytestostring) | | Returns a string representation of the Bytes object. | +| [toUint8Array()](./firestore_lite.bytes.md#bytestouint8array) | | Returns the underlying bytes in a new Uint8Array. | + +## Bytes.fromBase64String() + +Creates a new `Bytes` object from the given Base64 string, converting it to bytes. + +Signature: + +```typescript +static fromBase64String(base64: string): Bytes; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| base64 | string | The Base64 string used to create the Bytes object. | + +Returns: + +[Bytes](./firestore_lite.bytes.md#bytes_class) + +## Bytes.fromUint8Array() + +Creates a new `Bytes` object from the given Uint8Array. + +Signature: + +```typescript +static fromUint8Array(array: Uint8Array): Bytes; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| array | Uint8Array | The Uint8Array used to create the Bytes object. | + +Returns: + +[Bytes](./firestore_lite.bytes.md#bytes_class) + +## Bytes.isEqual() + +Returns true if this `Bytes` object is equal to the provided one. + +Signature: + +```typescript +isEqual(other: Bytes): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| other | [Bytes](./firestore_lite.bytes.md#bytes_class) | The Bytes object to compare against. | + +Returns: + +boolean + +true if this `Bytes` object is equal to the provided one. + +## Bytes.toBase64() + +Returns the underlying bytes as a Base64-encoded string. + +Signature: + +```typescript +toBase64(): string; +``` +Returns: + +string + +The Base64-encoded string created from the `Bytes` object. + +## Bytes.toString() + +Returns a string representation of the `Bytes` object. + +Signature: + +```typescript +toString(): string; +``` +Returns: + +string + +A string representation of the `Bytes` object. + +## Bytes.toUint8Array() + +Returns the underlying bytes in a new `Uint8Array`. + +Signature: + +```typescript +toUint8Array(): Uint8Array; +``` +Returns: + +Uint8Array + +The Uint8Array created from the `Bytes` object. + diff --git a/docs-devsite/firestore_lite.collectionreference.md b/docs-devsite/firestore_lite.collectionreference.md new file mode 100644 index 00000000000..d446560a02f --- /dev/null +++ b/docs-devsite/firestore_lite.collectionreference.md @@ -0,0 +1,121 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# CollectionReference class +A `CollectionReference` object can be used for adding documents, getting document references, and querying for documents (using [query()](./firestore_.md#query)). + +Signature: + +```typescript +export declare class CollectionReference extends Query +``` +Extends: [Query](./firestore_lite.query.md#query_class)<T> + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [id](./firestore_lite.collectionreference.md#collectionreferenceid) | | string | The collection's identifier. | +| [parent](./firestore_lite.collectionreference.md#collectionreferenceparent) | | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> \| null | A reference to the containing DocumentReference if this is a subcollection. If this isn't a subcollection, the reference is null. | +| [path](./firestore_lite.collectionreference.md#collectionreferencepath) | | string | A string representing the path of the referenced collection (relative to the root of the database). | +| [type](./firestore_lite.collectionreference.md#collectionreferencetype) | | (not declared) | The type of this Firestore reference. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [withConverter(converter)](./firestore_lite.collectionreference.md#collectionreferencewithconverter) | | Applies a custom data converter to this CollectionReference, allowing you to use your own custom model objects with Firestore. When you call [addDoc()](./firestore_.md#adddoc) with the returned CollectionReference instance, the provided converter will convert between Firestore data and your custom type U. | +| [withConverter(converter)](./firestore_lite.collectionreference.md#collectionreferencewithconverter) | | Removes the current converter. | + +## CollectionReference.id + +The collection's identifier. + +Signature: + +```typescript +get id(): string; +``` + +## CollectionReference.parent + +A reference to the containing `DocumentReference` if this is a subcollection. If this isn't a subcollection, the reference is null. + +Signature: + +```typescript +get parent(): DocumentReference | null; +``` + +## CollectionReference.path + +A string representing the path of the referenced collection (relative to the root of the database). + +Signature: + +```typescript +get path(): string; +``` + +## CollectionReference.type + +The type of this Firestore reference. + +Signature: + +```typescript +readonly type = "collection"; +``` + +## CollectionReference.withConverter() + +Applies a custom data converter to this `CollectionReference`, allowing you to use your own custom model objects with Firestore. When you call [addDoc()](./firestore_.md#adddoc) with the returned `CollectionReference` instance, the provided converter will convert between Firestore data and your custom type `U`. + +Signature: + +```typescript +withConverter(converter: FirestoreDataConverter): CollectionReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| converter | [FirestoreDataConverter](./firestore_lite.firestoredataconverter.md#firestoredataconverter_interface)<U> | Converts objects to and from Firestore. | + +Returns: + +[CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<U> + +A `CollectionReference` that uses the provided converter. + +## CollectionReference.withConverter() + +Removes the current converter. + +Signature: + +```typescript +withConverter(converter: null): CollectionReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| converter | null | null removes the current converter. | + +Returns: + +[CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> + +A `CollectionReference` that does not use a converter. + diff --git a/docs-devsite/firestore_lite.documentdata.md b/docs-devsite/firestore_lite.documentdata.md new file mode 100644 index 00000000000..09b5eb64b48 --- /dev/null +++ b/docs-devsite/firestore_lite.documentdata.md @@ -0,0 +1,19 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# DocumentData interface +Document data (for use with [setDoc()](./firestore_lite.md#setdoc)) consists of fields mapped to values. + +Signature: + +```typescript +export declare interface DocumentData +``` diff --git a/docs-devsite/firestore_lite.documentreference.md b/docs-devsite/firestore_lite.documentreference.md new file mode 100644 index 00000000000..0e307435949 --- /dev/null +++ b/docs-devsite/firestore_lite.documentreference.md @@ -0,0 +1,142 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# DocumentReference class +A `DocumentReference` refers to a document location in a Firestore database and can be used to write, read, or listen to the location. The document at the referenced location may or may not exist. + +Signature: + +```typescript +export declare class DocumentReference +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [converter](./firestore_lite.documentreference.md#documentreferenceconverter) | | [FirestoreDataConverter](./firestore_lite.firestoredataconverter.md#firestoredataconverter_interface)<T> \| null | If provided, the FirestoreDataConverter associated with this instance. | +| [firestore](./firestore_lite.documentreference.md#documentreferencefirestore) | | [Firestore](./firestore_lite.firestore.md#firestore_class) | The [Firestore](./firestore_.firestore.md#firestore_class) instance the document is in. This is useful for performing transactions, for example. | +| [id](./firestore_lite.documentreference.md#documentreferenceid) | | string | The document's identifier within its collection. | +| [parent](./firestore_lite.documentreference.md#documentreferenceparent) | | [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | The collection this DocumentReference belongs to. | +| [path](./firestore_lite.documentreference.md#documentreferencepath) | | string | A string representing the path of the referenced document (relative to the root of the database). | +| [type](./firestore_lite.documentreference.md#documentreferencetype) | | (not declared) | The type of this Firestore reference. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [withConverter(converter)](./firestore_lite.documentreference.md#documentreferencewithconverter) | | Applies a custom data converter to this DocumentReference, allowing you to use your own custom model objects with Firestore. When you call [setDoc()](./firestore_lite.md#setdoc), [getDoc()](./firestore_lite.md#getdoc), etc. with the returned DocumentReference instance, the provided converter will convert between Firestore data and your custom type U. | +| [withConverter(converter)](./firestore_lite.documentreference.md#documentreferencewithconverter) | | Removes the current converter. | + +## DocumentReference.converter + +If provided, the `FirestoreDataConverter` associated with this instance. + +Signature: + +```typescript +readonly converter: FirestoreDataConverter | null; +``` + +## DocumentReference.firestore + +The [Firestore](./firestore_.firestore.md#firestore_class) instance the document is in. This is useful for performing transactions, for example. + +Signature: + +```typescript +readonly firestore: Firestore; +``` + +## DocumentReference.id + +The document's identifier within its collection. + +Signature: + +```typescript +get id(): string; +``` + +## DocumentReference.parent + +The collection this `DocumentReference` belongs to. + +Signature: + +```typescript +get parent(): CollectionReference; +``` + +## DocumentReference.path + +A string representing the path of the referenced document (relative to the root of the database). + +Signature: + +```typescript +get path(): string; +``` + +## DocumentReference.type + +The type of this Firestore reference. + +Signature: + +```typescript +readonly type = "document"; +``` + +## DocumentReference.withConverter() + +Applies a custom data converter to this `DocumentReference`, allowing you to use your own custom model objects with Firestore. When you call [setDoc()](./firestore_lite.md#setdoc), [getDoc()](./firestore_lite.md#getdoc), etc. with the returned `DocumentReference` instance, the provided converter will convert between Firestore data and your custom type `U`. + +Signature: + +```typescript +withConverter(converter: FirestoreDataConverter): DocumentReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| converter | [FirestoreDataConverter](./firestore_lite.firestoredataconverter.md#firestoredataconverter_interface)<U> | Converts objects to and from Firestore. | + +Returns: + +[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<U> + +A `DocumentReference` that uses the provided converter. + +## DocumentReference.withConverter() + +Removes the current converter. + +Signature: + +```typescript +withConverter(converter: null): DocumentReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| converter | null | null removes the current converter. | + +Returns: + +[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> + +A `DocumentReference` that does not use a converter. + diff --git a/docs-devsite/firestore_lite.documentsnapshot.md b/docs-devsite/firestore_lite.documentsnapshot.md new file mode 100644 index 00000000000..cfea1feb919 --- /dev/null +++ b/docs-devsite/firestore_lite.documentsnapshot.md @@ -0,0 +1,125 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# DocumentSnapshot class +A `DocumentSnapshot` contains data read from a document in your Firestore database. The data can be extracted with `.data()` or `.get()` to get a specific field. + +For a `DocumentSnapshot` that points to a non-existing document, any data access will return 'undefined'. You can use the `exists()` method to explicitly verify a document's existence. + +Signature: + +```typescript +export declare class DocumentSnapshot +``` + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)()](./firestore_lite.documentsnapshot.md#documentsnapshotconstructor) | | Constructs a new instance of the DocumentSnapshot class | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [id](./firestore_lite.documentsnapshot.md#documentsnapshotid) | | string | Property of the DocumentSnapshot that provides the document's ID. | +| [ref](./firestore_lite.documentsnapshot.md#documentsnapshotref) | | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | The DocumentReference for the document included in the DocumentSnapshot. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [data()](./firestore_lite.documentsnapshot.md#documentsnapshotdata) | | Retrieves all fields in the document as an Object. Returns undefined if the document doesn't exist. | +| [exists()](./firestore_lite.documentsnapshot.md#documentsnapshotexists) | | Signals whether or not the document at the snapshot's location exists. | +| [get(fieldPath)](./firestore_lite.documentsnapshot.md#documentsnapshotget) | | Retrieves the field specified by fieldPath. Returns undefined if the document or field doesn't exist. | + +## DocumentSnapshot.(constructor) + +Constructs a new instance of the `DocumentSnapshot` class + +Signature: + +```typescript +protected constructor(); +``` + +## DocumentSnapshot.id + +Property of the `DocumentSnapshot` that provides the document's ID. + +Signature: + +```typescript +get id(): string; +``` + +## DocumentSnapshot.ref + +The `DocumentReference` for the document included in the `DocumentSnapshot`. + +Signature: + +```typescript +get ref(): DocumentReference; +``` + +## DocumentSnapshot.data() + +Retrieves all fields in the document as an `Object`. Returns `undefined` if the document doesn't exist. + +Signature: + +```typescript +data(): T | undefined; +``` +Returns: + +T \| undefined + +An `Object` containing all fields in the document or `undefined` if the document doesn't exist. + +## DocumentSnapshot.exists() + +Signals whether or not the document at the snapshot's location exists. + +Signature: + +```typescript +exists(): this is QueryDocumentSnapshot; +``` +Returns: + +this is [QueryDocumentSnapshot](./firestore_lite.querydocumentsnapshot.md#querydocumentsnapshot_class)<T> + +true if the document exists. + +## DocumentSnapshot.get() + +Retrieves the field specified by `fieldPath`. Returns `undefined` if the document or field doesn't exist. + +Signature: + +```typescript +get(fieldPath: string | FieldPath): any; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldPath | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The path (for example 'foo' or 'foo.bar') to a specific field. | + +Returns: + +any + +The data at the specified field location or undefined if no such field exists in the document. + diff --git a/docs-devsite/firestore_lite.fieldpath.md b/docs-devsite/firestore_lite.fieldpath.md new file mode 100644 index 00000000000..ea449fc065b --- /dev/null +++ b/docs-devsite/firestore_lite.fieldpath.md @@ -0,0 +1,72 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FieldPath class +A `FieldPath` refers to a field in a document. The path may consist of a single field name (referring to a top-level field in the document), or a list of field names (referring to a nested field in the document). + +Create a `FieldPath` by providing field names. If more than one field name is provided, the path will point to a nested field in a document. + +Signature: + +```typescript +export declare class FieldPath +``` + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(fieldNames)](./firestore_lite.fieldpath.md#fieldpathconstructor) | | Creates a FieldPath from the provided field names. If more than one field name is provided, the path will point to a nested field in a document. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [isEqual(other)](./firestore_lite.fieldpath.md#fieldpathisequal) | | Returns true if this FieldPath is equal to the provided one. | + +## FieldPath.(constructor) + +Creates a `FieldPath` from the provided field names. If more than one field name is provided, the path will point to a nested field in a document. + +Signature: + +```typescript +constructor(...fieldNames: string[]); +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldNames | string\[\] | A list of field names. | + +## FieldPath.isEqual() + +Returns true if this `FieldPath` is equal to the provided one. + +Signature: + +```typescript +isEqual(other: FieldPath): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| other | [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The FieldPath to compare against. | + +Returns: + +boolean + +true if this `FieldPath` is equal to the provided one. + diff --git a/docs-devsite/firestore_lite.fieldvalue.md b/docs-devsite/firestore_lite.fieldvalue.md new file mode 100644 index 00000000000..454693c9771 --- /dev/null +++ b/docs-devsite/firestore_lite.fieldvalue.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FieldValue class +Sentinel values that can be used when writing document fields with `set()` or `update()`. + +Signature: + +```typescript +export declare abstract class FieldValue +``` + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [isEqual(other)](./firestore_lite.fieldvalue.md#fieldvalueisequal) | | Compares FieldValues for equality. | + +## FieldValue.isEqual() + +Compares `FieldValue`s for equality. + +Signature: + +```typescript +abstract isEqual(other: FieldValue): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| other | [FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) | | + +Returns: + +boolean + diff --git a/docs-devsite/firestore_lite.firestore.md b/docs-devsite/firestore_lite.firestore.md new file mode 100644 index 00000000000..2edac7aa130 --- /dev/null +++ b/docs-devsite/firestore_lite.firestore.md @@ -0,0 +1,68 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Firestore class +The Cloud Firestore service interface. + +Do not call this constructor directly. Instead, use [getFirestore()](./firestore_.md#getfirestore). + +Signature: + +```typescript +export declare class Firestore +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [app](./firestore_lite.firestore.md#firestoreapp) | | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this Firestore service instance. | +| [type](./firestore_lite.firestore.md#firestoretype) | | 'firestore-lite' \| 'firestore' | Whether it's a Firestore or Firestore Lite instance. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [toJSON()](./firestore_lite.firestore.md#firestoretojson) | | Returns a JSON-serializable representation of this Firestore instance. | + +## Firestore.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this `Firestore` service instance. + +Signature: + +```typescript +get app(): FirebaseApp; +``` + +## Firestore.type + +Whether it's a Firestore or Firestore Lite instance. + +Signature: + +```typescript +type: 'firestore-lite' | 'firestore'; +``` + +## Firestore.toJSON() + +Returns a JSON-serializable representation of this `Firestore` instance. + +Signature: + +```typescript +toJSON(): object; +``` +Returns: + +object + diff --git a/docs-devsite/firestore_lite.firestoredataconverter.md b/docs-devsite/firestore_lite.firestoredataconverter.md new file mode 100644 index 00000000000..00510e0c22b --- /dev/null +++ b/docs-devsite/firestore_lite.firestoredataconverter.md @@ -0,0 +1,130 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FirestoreDataConverter interface +Converter used by `withConverter()` to transform user objects of type `T` into Firestore data. + +Using the converter allows you to specify generic type arguments when storing and retrieving objects from Firestore. + +Signature: + +```typescript +export declare interface FirestoreDataConverter +``` + +## Methods + +| Method | Description | +| --- | --- | +| [fromFirestore(snapshot)](./firestore_lite.firestoredataconverter.md#firestoredataconverterfromfirestore) | Called by the Firestore SDK to convert Firestore data into an object of type T. You can access your data by calling: snapshot.data(). | +| [toFirestore(modelObject)](./firestore_lite.firestoredataconverter.md#firestoredataconvertertofirestore) | Called by the Firestore SDK to convert a custom model object of type T into a plain Javascript object (suitable for writing directly to the Firestore database). Used with [setDoc()](./firestore_lite.md#setdoc), and .The WithFieldValue<T> type extends T to also allow FieldValues such as [deleteField()](./firestore_.md#deletefield) to be used as property values. | +| [toFirestore(modelObject, options)](./firestore_lite.firestoredataconverter.md#firestoredataconvertertofirestore) | Called by the Firestore SDK to convert a custom model object of type T into a plain Javascript object (suitable for writing directly to the Firestore database). Used with [setDoc()](./firestore_lite.md#setdoc), and with merge:true or mergeFields.The PartialWithFieldValue<T> type extends Partial<T> to allow FieldValues such as [arrayUnion()](./firestore_.md#arrayunion) to be used as property values. It also supports nested Partial by allowing nested fields to be omitted. | + +## FirestoreDataConverter.fromFirestore() + +Called by the Firestore SDK to convert Firestore data into an object of type T. You can access your data by calling: `snapshot.data()`. + +Signature: + +```typescript +fromFirestore(snapshot: QueryDocumentSnapshot): T; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| snapshot | [QueryDocumentSnapshot](./firestore_lite.querydocumentsnapshot.md#querydocumentsnapshot_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> | A QueryDocumentSnapshot containing your data and metadata. | + +Returns: + +T + +## FirestoreDataConverter.toFirestore() + +Called by the Firestore SDK to convert a custom model object of type `T` into a plain Javascript object (suitable for writing directly to the Firestore database). Used with [setDoc()](./firestore_lite.md#setdoc), and . + +The `WithFieldValue` type extends `T` to also allow FieldValues such as [deleteField()](./firestore_.md#deletefield) to be used as property values. + +Signature: + +```typescript +toFirestore(modelObject: WithFieldValue): DocumentData; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| modelObject | [WithFieldValue](./firestore_lite.md#withfieldvalue)<T> | | + +Returns: + +[DocumentData](./firestore_lite.documentdata.md#documentdata_interface) + +## FirestoreDataConverter.toFirestore() + +Called by the Firestore SDK to convert a custom model object of type `T` into a plain Javascript object (suitable for writing directly to the Firestore database). Used with [setDoc()](./firestore_lite.md#setdoc), and with `merge:true` or `mergeFields`. + +The `PartialWithFieldValue` type extends `Partial` to allow FieldValues such as [arrayUnion()](./firestore_.md#arrayunion) to be used as property values. It also supports nested `Partial` by allowing nested fields to be omitted. + +Signature: + +```typescript +toFirestore(modelObject: PartialWithFieldValue, options: SetOptions): DocumentData; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| modelObject | [PartialWithFieldValue](./firestore_lite.md#partialwithfieldvalue)<T> | | +| options | [SetOptions](./firestore_lite.md#setoptions) | | + +Returns: + +[DocumentData](./firestore_lite.documentdata.md#documentdata_interface) + +### Example + + +```typescript +class Post { + constructor(readonly title: string, readonly author: string) {} + + toString(): string { + return this.title + ', by ' + this.author; + } +} + +const postConverter = { + toFirestore(post: WithFieldValue): DocumentData { + return {title: post.title, author: post.author}; + }, + fromFirestore(snapshot: QueryDocumentSnapshot): Post { + const data = snapshot.data(options)!; + return new Post(data.title, data.author); + } +}; + +const postSnap = await firebase.firestore() + .collection('posts') + .withConverter(postConverter) + .doc().get(); +const post = postSnap.data(); +if (post !== undefined) { + post.title; // string + post.toString(); // Should be defined + post.someNonExistentProperty; // TS error +} + +``` + diff --git a/docs-devsite/firestore_lite.firestoreerror.md b/docs-devsite/firestore_lite.firestoreerror.md new file mode 100644 index 00000000000..e3c6dd23029 --- /dev/null +++ b/docs-devsite/firestore_lite.firestoreerror.md @@ -0,0 +1,58 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FirestoreError class +An error returned by a Firestore operation. + +Signature: + +```typescript +export declare class FirestoreError extends FirebaseError +``` +Extends: [FirebaseError](./util.firebaseerror.md#firebaseerror_class) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [code](./firestore_lite.firestoreerror.md#firestoreerrorcode) | | [FirestoreErrorCode](./firestore_lite.md#firestoreerrorcode) | The backend error code associated with this error. | +| [message](./firestore_lite.firestoreerror.md#firestoreerrormessage) | | string | A custom error description. | +| [stack](./firestore_lite.firestoreerror.md#firestoreerrorstack) | | string | The stack of the error. | + +## FirestoreError.code + +The backend error code associated with this error. + +Signature: + +```typescript +readonly code: FirestoreErrorCode; +``` + +## FirestoreError.message + +A custom error description. + +Signature: + +```typescript +readonly message: string; +``` + +## FirestoreError.stack + +The stack of the error. + +Signature: + +```typescript +readonly stack?: string; +``` diff --git a/docs-devsite/firestore_lite.geopoint.md b/docs-devsite/firestore_lite.geopoint.md new file mode 100644 index 00000000000..23576c41d8d --- /dev/null +++ b/docs-devsite/firestore_lite.geopoint.md @@ -0,0 +1,117 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# GeoPoint class +An immutable object representing a geographic location in Firestore. The location is represented as latitude/longitude pair. + +Latitude values are in the range of \[-90, 90\]. Longitude values are in the range of \[-180, 180\]. + +Signature: + +```typescript +export declare class GeoPoint +``` + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(latitude, longitude)](./firestore_lite.geopoint.md#geopointconstructor) | | Creates a new immutable GeoPoint object with the provided latitude and longitude values. | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [latitude](./firestore_lite.geopoint.md#geopointlatitude) | | number | The latitude of this GeoPoint instance. | +| [longitude](./firestore_lite.geopoint.md#geopointlongitude) | | number | The longitude of this GeoPoint instance. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [isEqual(other)](./firestore_lite.geopoint.md#geopointisequal) | | Returns true if this GeoPoint is equal to the provided one. | +| [toJSON()](./firestore_lite.geopoint.md#geopointtojson) | | Returns a JSON-serializable representation of this GeoPoint. | + +## GeoPoint.(constructor) + +Creates a new immutable `GeoPoint` object with the provided latitude and longitude values. + +Signature: + +```typescript +constructor(latitude: number, longitude: number); +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| latitude | number | The latitude as number between -90 and 90. | +| longitude | number | The longitude as number between -180 and 180. | + +## GeoPoint.latitude + +The latitude of this `GeoPoint` instance. + +Signature: + +```typescript +get latitude(): number; +``` + +## GeoPoint.longitude + +The longitude of this `GeoPoint` instance. + +Signature: + +```typescript +get longitude(): number; +``` + +## GeoPoint.isEqual() + +Returns true if this `GeoPoint` is equal to the provided one. + +Signature: + +```typescript +isEqual(other: GeoPoint): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| other | [GeoPoint](./firestore_lite.geopoint.md#geopoint_class) | The GeoPoint to compare against. | + +Returns: + +boolean + +true if this `GeoPoint` is equal to the provided one. + +## GeoPoint.toJSON() + +Returns a JSON-serializable representation of this GeoPoint. + +Signature: + +```typescript +toJSON(): { + latitude: number; + longitude: number; + }; +``` +Returns: + +{ latitude: number; longitude: number; } + diff --git a/docs-devsite/firestore_lite.md b/docs-devsite/firestore_lite.md new file mode 100644 index 00000000000..3754cda22b7 --- /dev/null +++ b/docs-devsite/firestore_lite.md @@ -0,0 +1,1443 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# @firebase/firestore/lite + +## Functions + +| Function | Description | +| --- | --- | +| function(app...) | +| [getFirestore(app)](./firestore_lite.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. | +| [initializeFirestore(app, settings)](./firestore_lite.md#initializefirestore) | Initializes a new instance of Cloud Firestore with the provided settings. Can only be called before any other functions, including [getFirestore()](./firestore_.md#getfirestore). If the custom settings are empty, this function is equivalent to calling [getFirestore()](./firestore_.md#getfirestore). | +| function(firestore...) | +| [collection(firestore, path, pathSegments)](./firestore_lite.md#collection) | Gets a CollectionReference instance that refers to the collection at the specified absolute path. | +| [collectionGroup(firestore, collectionId)](./firestore_lite.md#collectiongroup) | Creates and returns a new Query instance that includes all documents in the database that are contained in a collection or subcollection with the given collectionId. | +| [connectFirestoreEmulator(firestore, host, port, options)](./firestore_lite.md#connectfirestoreemulator) | Modify this instance to communicate with the Cloud Firestore emulator.Note: This must be called before this instance has been used to do any operations. | +| [doc(firestore, path, pathSegments)](./firestore_lite.md#doc) | Gets a DocumentReference instance that refers to the document at the specified absolute path. | +| [runTransaction(firestore, updateFunction, options)](./firestore_lite.md#runtransaction) | Executes the given updateFunction and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, Cloud Firestore retries the updateFunction. If it fails to commit after 5 attempts, the transaction fails.The maximum number of writes allowed in a single transaction is 500. | +| [terminate(firestore)](./firestore_lite.md#terminate) | Terminates the provided Firestore instance.After calling terminate() only the clearIndexedDbPersistence() functions may be used. Any other function will throw a FirestoreError. Termination does not cancel any pending writes, and any promises that are awaiting a response from the server will not be resolved.To restart after termination, create a new instance of Firestore with [getFirestore()](./firestore_.md#getfirestore).Note: Under normal circumstances, calling terminate() is not required. This function is useful only when you want to force this instance to release all of its resources or in combination with [clearIndexedDbPersistence()](./firestore_.md#clearindexeddbpersistence) to ensure that all local state is destroyed between test runs. | +| [writeBatch(firestore)](./firestore_lite.md#writebatch) | Creates a write batch, used for performing multiple writes as a single atomic operation. The maximum number of writes allowed in a single WriteBatch is 500.The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | +| function() | +| [deleteField()](./firestore_lite.md#deletefield) | Returns a sentinel for use with [updateDoc()](./firestore_lite.md#updatedoc) or [setDoc()](./firestore_lite.md#setdoc) with {merge: true} to mark a field for deletion. | +| [documentId()](./firestore_lite.md#documentid) | Returns a special sentinel FieldPath to refer to the ID of a document. It can be used in queries to sort or filter by the document ID. | +| [getFirestore()](./firestore_lite.md#getfirestore) | Returns the existing default [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. | +| [serverTimestamp()](./firestore_lite.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(elements...) | +| [arrayRemove(elements)](./firestore_lite.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_lite.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. | +| function(fieldPath...) | +| [orderBy(fieldPath, directionStr)](./firestore_lite.md#orderby) | Creates a [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class) that sorts the query result by the specified field, optionally in descending order instead of ascending.Note: Documents that do not contain the specified field will not be present in the query result. | +| [where(fieldPath, opStr, value)](./firestore_lite.md#where) | Creates a [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) that enforces that documents must contain the specified field and that the value should satisfy the relation constraint provided. | +| function(fieldValues...) | +| [endAt(fieldValues)](./firestore_lite.md#endat) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | +| [endBefore(fieldValues)](./firestore_lite.md#endbefore) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | +| [startAfter(fieldValues)](./firestore_lite.md#startafter) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | +| [startAt(fieldValues)](./firestore_lite.md#startat) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | +| function(left...) | +| [aggregateQuerySnapshotEqual(left, right)](./firestore_lite.md#aggregatequerysnapshotequal) | Compares two AggregateQuerySnapshot instances for equality.Two AggregateQuerySnapshot instances are considered "equal" if they have underlying queries that compare equal, and the same data. | +| [queryEqual(left, right)](./firestore_lite.md#queryequal) | Returns true if the provided queries point to the same collection and apply the same constraints. | +| [refEqual(left, right)](./firestore_lite.md#refequal) | Returns true if the provided references are equal. | +| [snapshotEqual(left, right)](./firestore_lite.md#snapshotequal) | Returns true if the provided snapshots are equal. | +| function(limit...) | +| [limit(limit)](./firestore_lite.md#limit) | Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the first matching documents. | +| [limitToLast(limit)](./firestore_lite.md#limittolast) | Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the last matching documents.You must specify at least one orderBy clause for limitToLast queries, otherwise an exception will be thrown during execution. | +| function(logLevel...) | +| [setLogLevel(logLevel)](./firestore_lite.md#setloglevel) | Sets the verbosity of Cloud Firestore logs (debug, error, or silent). | +| function(n...) | +| [increment(n)](./firestore_lite.md#increment) | 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 increment the field's current value by the given value.If either the operand or the current field value uses floating point precision, all arithmetic follows IEEE 754 semantics. If both values are integers, values outside of JavaScript's safe number range (Number.MIN_SAFE_INTEGER to Number.MAX_SAFE_INTEGER) are also subject to precision loss. Furthermore, once processed by the Firestore backend, all integer operations are capped between -2^63 and 2^63-1.If the current field value is not of type number, or if the field does not yet exist, the transformation sets the field to the given value. | +| function(query...) | +| [getCount(query)](./firestore_lite.md#getcount) | Calculates the number of documents in the result set of the given query, without actually downloading the documents.Using this function to count the documents is efficient because only the final count, not the documents' data, is downloaded. This function can even count the documents if the result set would be prohibitively large to download entirely (e.g. thousands of documents). | +| [getDocs(query)](./firestore_lite.md#getdocs) | Executes the query and returns the results as a [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class).All queries are executed directly by the server, even if the the query was previously executed. Recent modifications are only reflected in the retrieved results if they have already been applied by the backend. If the client is offline, the operation fails. To see previously cached result and local modifications, use the full Firestore SDK. | +| [query(query, queryConstraints)](./firestore_lite.md#query) | Creates a new immutable instance of [Query](./firestore_.query.md#query_class) that is extended to also include additional query constraints. | +| function(reference...) | +| [addDoc(reference, data)](./firestore_lite.md#adddoc) | Add a new document to specified CollectionReference with the given data, assigning it a document ID automatically.The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | +| [collection(reference, path, pathSegments)](./firestore_lite.md#collection) | Gets a CollectionReference instance that refers to a subcollection of reference at the the specified relative path. | +| [collection(reference, path, pathSegments)](./firestore_lite.md#collection) | Gets a CollectionReference instance that refers to a subcollection of reference at the the specified relative path. | +| [deleteDoc(reference)](./firestore_lite.md#deletedoc) | Deletes the document referred to by the specified DocumentReference.The deletion will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the delete fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | +| [doc(reference, path, pathSegments)](./firestore_lite.md#doc) | Gets a DocumentReference instance that refers to a document within reference at the specified relative path. If no path is specified, an automatically-generated unique ID will be used for the returned DocumentReference. | +| [doc(reference, path, pathSegments)](./firestore_lite.md#doc) | Gets a DocumentReference instance that refers to a document within reference at the specified relative path. | +| [getDoc(reference)](./firestore_lite.md#getdoc) | Reads the document referred to by the specified document reference.All documents are directly fetched from the server, even if the document was previously read or modified. Recent modifications are only reflected in the retrieved DocumentSnapshot if they have already been applied by the backend. If the client is offline, the read fails. If you like to use caching or see local modifications, please use the full Firestore SDK. | +| [setDoc(reference, data)](./firestore_lite.md#setdoc) | Writes to the document referred to by the specified DocumentReference. If the document does not yet exist, it will be created.The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | +| [setDoc(reference, data, options)](./firestore_lite.md#setdoc) | Writes to the document referred to by the specified DocumentReference. If the document does not yet exist, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document.The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | +| [updateDoc(reference, data)](./firestore_lite.md#updatedoc) | Updates fields in the document referred to by the specified DocumentReference. The update will fail if applied to a document that does not exist.The result of this update will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the update fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | +| [updateDoc(reference, field, value, moreFieldsAndValues)](./firestore_lite.md#updatedoc) | Updates fields in the document referred to by the specified DocumentReference The update will fail if applied to a document that does not exist.Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects.The result of this update will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the update fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | +| function(snapshot...) | +| [endAt(snapshot)](./firestore_lite.md#endat) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided document (inclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | +| [endBefore(snapshot)](./firestore_lite.md#endbefore) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | +| [startAfter(snapshot)](./firestore_lite.md#startafter) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. | +| [startAt(snapshot)](./firestore_lite.md#startat) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of this query. | + +## Classes + +| Class | Description | +| --- | --- | +| [AggregateField](./firestore_lite.aggregatefield.md#aggregatefield_class) | Represents an aggregation that can be performed by Firestore. | +| [AggregateQuerySnapshot](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshot_class) | The results of executing an aggregation query. | +| [Bytes](./firestore_lite.bytes.md#bytes_class) | An immutable object representing an array of bytes. | +| [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class) | A CollectionReference object can be used for adding documents, getting document references, and querying for documents (using [query()](./firestore_.md#query)). | +| [DocumentReference](./firestore_lite.documentreference.md#documentreference_class) | A DocumentReference refers to a document location in a Firestore database and can be used to write, read, or listen to the location. The document at the referenced location may or may not exist. | +| [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class) | A DocumentSnapshot contains data read from a document in your Firestore database. The data can be extracted with .data() or .get(<field>) to get a specific field.For a DocumentSnapshot that points to a non-existing document, any data access will return 'undefined'. You can use the exists() method to explicitly verify a document's existence. | +| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | A FieldPath refers to a field in a document. The path may consist of a single field name (referring to a top-level field in the document), or a list of field names (referring to a nested field in the document).Create a FieldPath by providing field names. If more than one field name is provided, the path will point to a nested field in a document. | +| [FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) | Sentinel values that can be used when writing document fields with set() or update(). | +| [Firestore](./firestore_lite.firestore.md#firestore_class) | The Cloud Firestore service interface.Do not call this constructor directly. Instead, use [getFirestore()](./firestore_.md#getfirestore). | +| [FirestoreError](./firestore_lite.firestoreerror.md#firestoreerror_class) | An error returned by a Firestore operation. | +| [GeoPoint](./firestore_lite.geopoint.md#geopoint_class) | An immutable object representing a geographic location in Firestore. The location is represented as latitude/longitude pair.Latitude values are in the range of \[-90, 90\]. Longitude values are in the range of \[-180, 180\]. | +| [Query](./firestore_lite.query.md#query_class) | A Query refers to a query which you can read or listen to. You can also construct refined Query objects by adding filters and ordering. | +| [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) | A QueryConstraint is used to narrow the set of documents returned by a Firestore query. QueryConstraints are created by invoking [where()](./firestore_.md#where), [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit), [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryConstraint. | +| [QueryDocumentSnapshot](./firestore_lite.querydocumentsnapshot.md#querydocumentsnapshot_class) | A QueryDocumentSnapshot contains data read from a document in your Firestore database as part of a query. The document is guaranteed to exist and its data can be extracted with .data() or .get(<field>) to get a specific field.A QueryDocumentSnapshot offers the same API surface as a DocumentSnapshot. Since query results contain only existing documents, the exists property will always be true and data() will never return 'undefined'. | +| [QueryEndAtConstraint](./firestore_lite.queryendatconstraint.md#queryendatconstraint_class) | A QueryEndAtConstraint is used to exclude documents from the end of a result set returned by a Firestore query. QueryEndAtConstraints are created by invoking [endAt()](./firestore_.md#endat) or [endBefore()](./firestore_.md#endbefore) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryEndAtConstraint. | +| [QueryFieldFilterConstraint](./firestore_lite.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) | A QueryFieldFilterConstraint is used to narrow the set of documents returned by a Firestore query by filtering on one or more document fields. QueryFieldFilterConstraints are created by invoking [where()](./firestore_.md#where) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryFieldFilterConstraint. | +| [QueryLimitConstraint](./firestore_lite.querylimitconstraint.md#querylimitconstraint_class) | A QueryLimitConstraint is used to limit the number of documents returned by a Firestore query. QueryLimitConstraints are created by invoking [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryLimitConstraint. | +| [QueryOrderByConstraint](./firestore_lite.queryorderbyconstraint.md#queryorderbyconstraint_class) | A QueryOrderByConstraint is used to sort the set of documents returned by a Firestore query. QueryOrderByConstraints are created by invoking [orderBy()](./firestore_.md#orderby) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryOrderByConstraint.Note: Documents that do not contain the orderBy field will not be present in the query result. | +| [QuerySnapshot](./firestore_lite.querysnapshot.md#querysnapshot_class) | A QuerySnapshot contains zero or more DocumentSnapshot objects representing the results of a query. The documents can be accessed as an array via the docs property or enumerated using the forEach method. The number of documents can be determined via the empty and size properties. | +| [QueryStartAtConstraint](./firestore_lite.querystartatconstraint.md#querystartatconstraint_class) | A QueryStartAtConstraint is used to exclude documents from the start of a result set returned by a Firestore query. QueryStartAtConstraints are created by invoking [startAt()](./firestore_.md#startat) or [startAfter()](./firestore_.md#startafter) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryStartAtConstraint. | +| [Timestamp](./firestore_lite.timestamp.md#timestamp_class) | A Timestamp represents a point in time independent of any time zone or calendar, represented as seconds and fractions of seconds at nanosecond resolution in UTC Epoch time.It is encoded using the Proleptic Gregorian Calendar which extends the Gregorian calendar backwards to year one. It is encoded assuming all minutes are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.For examples and further specifications, refer to the [Timestamp definition](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto). | +| [Transaction](./firestore_lite.transaction.md#transaction_class) | A reference to a transaction.The Transaction object passed to a transaction's updateFunction provides the methods to read and write data within the transaction context. See [runTransaction()](./firestore_.md#runtransaction). | +| [WriteBatch](./firestore_lite.writebatch.md#writebatch_class) | A write batch, used to perform multiple writes as a single atomic unit.A WriteBatch object can be acquired by calling [writeBatch()](./firestore_.md#writebatch). It provides methods for adding writes to the write batch. None of the writes will be committed (or visible locally) until [WriteBatch.commit()](./firestore_.writebatch.md#writebatchcommit) is called. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [AggregateSpec](./firestore_lite.aggregatespec.md#aggregatespec_interface) | A type whose property values are all AggregateField objects. | +| [DocumentData](./firestore_lite.documentdata.md#documentdata_interface) | Document data (for use with [setDoc()](./firestore_lite.md#setdoc)) consists of fields mapped to values. | +| [FirestoreDataConverter](./firestore_lite.firestoredataconverter.md#firestoredataconverter_interface) | Converter used by withConverter() to transform user objects of type T into Firestore data.Using the converter allows you to specify generic type arguments when storing and retrieving objects from Firestore. | +| [Settings](./firestore_lite.settings.md#settings_interface) | Specifies custom configurations for your Cloud Firestore instance. You must set these before invoking any other methods. | +| [TransactionOptions](./firestore_lite.transactionoptions.md#transactionoptions_interface) | Options to customize transaction behavior. | + +## Type Aliases + +| Type Alias | Description | +| --- | --- | +| [AddPrefixToKeys](./firestore_lite.md#addprefixtokeys) | Returns a new map where every key is prefixed with the outer key appended to a dot. | +| [AggregateFieldType](./firestore_lite.md#aggregatefieldtype) | The union of all AggregateField types that are supported by Firestore. | +| [AggregateSpecData](./firestore_lite.md#aggregatespecdata) | A type whose keys are taken from an AggregateSpec, and whose values are the result of the aggregation performed by the corresponding AggregateField from the input AggregateSpec. | +| [ChildUpdateFields](./firestore_lite.md#childupdatefields) | Helper for calculating the nested fields for a given type T1. This is needed to distribute union types such as undefined | {...} (happens for optional props) or {a: A} | {b: B}.In this use case, V is used to distribute the union types of T[K] on Record, since T[K] is evaluated as an expression and not distributed.See https://www.typescriptlang.org/docs/handbook/advanced-types.html\#distributive-conditional-types | +| [FirestoreErrorCode](./firestore_lite.md#firestoreerrorcode) | The set of Firestore status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.mdPossible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (e.g. an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation. | +| [NestedUpdateFields](./firestore_lite.md#nestedupdatefields) | For each field (e.g. 'bar'), find all nested keys (e.g. {'bar.baz': T1, 'bar.qux': T2}). Intersect them together to make a single map containing all possible keys that are all marked as optional | +| [OrderByDirection](./firestore_lite.md#orderbydirection) | The direction of a [orderBy()](./firestore_.md#orderby) clause is specified as 'desc' or 'asc' (descending or ascending). | +| [PartialWithFieldValue](./firestore_lite.md#partialwithfieldvalue) | Similar to Typescript's Partial<T>, but allows nested fields to be omitted and FieldValues to be passed in as property values. | +| [Primitive](./firestore_lite.md#primitive) | Primitive types. | +| [QueryConstraintType](./firestore_lite.md#queryconstrainttype) | Describes the different query constraints available in this SDK. | +| [QueryNonFilterConstraint](./firestore_lite.md#querynonfilterconstraint) | QueryNonFilterConstraint is a helper union type that represents QueryConstraints which are used to narrow or order the set of documents, but that do not explicitly filter on a document field. QueryNonFilterConstraints are created by invoking [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains the QueryConstraint. | +| [SetOptions](./firestore_lite.md#setoptions) | An options object that configures the behavior of [setDoc()](./firestore_lite.md#setdoc), and calls. These calls can be configured to perform granular merges instead of overwriting the target documents in their entirety by providing a SetOptions with merge: true. | +| [UnionToIntersection](./firestore_lite.md#uniontointersection) | Given a union type U = T1 | T2 | ..., returns an intersected type (T1 & T2 & ...).Uses distributive conditional types and inference from conditional types. This works because multiple candidates for the same type variable in contra-variant positions causes an intersection type to be inferred. https://www.typescriptlang.org/docs/handbook/advanced-types.html\#type-inference-in-conditional-types https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection-type | +| [UpdateData](./firestore_lite.md#updatedata) | Update data (for use with [updateDoc()](./firestore_.md#updatedoc)) that consists of field paths (e.g. 'foo' or 'foo.baz') mapped to values. Fields that contain dots reference nested fields within the document. FieldValues can be passed in as property values. | +| [WhereFilterOp](./firestore_lite.md#wherefilterop) | Filter conditions in a [where()](./firestore_.md#where) clause are specified using the strings '&lt;', '&lt;=', '==', '!=', '&gt;=', '&gt;', 'array-contains', 'in', 'array-contains-any', and 'not-in'. | +| [WithFieldValue](./firestore_lite.md#withfieldvalue) | Allows FieldValues to be passed in as a property value while maintaining type safety. | + +## 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. + +Signature: + +```typescript +export declare function getFirestore(app: FirebaseApp): Firestore; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance that the returned [Firestore](./firestore_.firestore.md#firestore_class) instance is associated with. | + +Returns: + +[Firestore](./firestore_lite.firestore.md#firestore_class) + +The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. + +## initializeFirestore() + +Initializes a new instance of Cloud Firestore with the provided settings. Can only be called before any other functions, including [getFirestore()](./firestore_.md#getfirestore). If the custom settings are empty, this function is equivalent to calling [getFirestore()](./firestore_.md#getfirestore). + +Signature: + +```typescript +export declare function initializeFirestore(app: FirebaseApp, settings: Settings): Firestore; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) with which the Firestore instance will be associated. | +| settings | [Settings](./firestore_lite.settings.md#settings_interface) | A settings object to configure the Firestore instance. | + +Returns: + +[Firestore](./firestore_lite.firestore.md#firestore_class) + +A newly initialized `Firestore` instance. + +## collection() + +Gets a `CollectionReference` instance that refers to the collection at the specified absolute path. + +Signature: + +```typescript +export declare function collection(firestore: Firestore, path: string, ...pathSegments: string[]): CollectionReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | A reference to the root Firestore instance. | +| path | string | A slash-separated path to a collection. | +| pathSegments | string\[\] | Additional path segments to apply relative to the first argument. | + +Returns: + +[CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> + +The `CollectionReference` instance. + +## Exceptions + +If the final path has an even number of segments and does not point to a collection. + +## collectionGroup() + +Creates and returns a new `Query` instance that includes all documents in the database that are contained in a collection or subcollection with the given `collectionId`. + +Signature: + +```typescript +export declare function collectionGroup(firestore: Firestore, collectionId: string): Query; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | A reference to the root Firestore instance. | +| collectionId | string | Identifies the collections to query over. Every collection or subcollection with this ID as the last segment of its path will be included. Cannot contain a slash. | + +Returns: + +[Query](./firestore_lite.query.md#query_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> + +The created `Query`. + +## connectFirestoreEmulator() + +Modify this instance to communicate with the Cloud Firestore emulator. + +Note: This must be called before this instance has been used to do any operations. + +Signature: + +```typescript +export declare function connectFirestoreEmulator(firestore: Firestore, host: string, port: number, options?: { + mockUserToken?: EmulatorMockTokenOptions | string; +}): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | The Firestore instance to configure to connect to the emulator. | +| host | string | the emulator host (ex: localhost). | +| port | number | the emulator port (ex: 9000). | +| options | { mockUserToken?: [EmulatorMockTokenOptions](./util.md#emulatormocktokenoptions) \| string; } | | + +Returns: + +void + +## doc() + +Gets a `DocumentReference` instance that refers to the document at the specified absolute path. + +Signature: + +```typescript +export declare function doc(firestore: Firestore, path: string, ...pathSegments: string[]): DocumentReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | A reference to the root Firestore instance. | +| path | string | A slash-separated path to a document. | +| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | + +Returns: + +[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> + +The `DocumentReference` instance. + +## Exceptions + +If the final path has an odd number of segments and does not point to a document. + +## runTransaction() + +Executes the given `updateFunction` and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, Cloud Firestore retries the `updateFunction`. If it fails to commit after 5 attempts, the transaction fails. + +The maximum number of writes allowed in a single transaction is 500. + +Signature: + +```typescript +export declare function runTransaction(firestore: Firestore, updateFunction: (transaction: Transaction) => Promise, options?: TransactionOptions): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | A reference to the Firestore database to run this transaction against. | +| updateFunction | (transaction: [Transaction](./firestore_lite.transaction.md#transaction_class)) => Promise<T> | The function to execute within the transaction context. | +| options | [TransactionOptions](./firestore_lite.transactionoptions.md#transactionoptions_interface) | An options object to configure maximum number of attempts to commit. | + +Returns: + +Promise<T> + +If the transaction completed successfully or was explicitly aborted (the `updateFunction` returned a failed promise), the promise returned by the `updateFunction `is returned here. Otherwise, if the transaction failed, a rejected promise with the corresponding failure error is returned. + +## terminate() + +Terminates the provided `Firestore` instance. + +After calling `terminate()` only the `clearIndexedDbPersistence()` functions may be used. Any other function will throw a `FirestoreError`. Termination does not cancel any pending writes, and any promises that are awaiting a response from the server will not be resolved. + +To restart after termination, create a new instance of `Firestore` with [getFirestore()](./firestore_.md#getfirestore). + +Note: Under normal circumstances, calling `terminate()` is not required. This function is useful only when you want to force this instance to release all of its resources or in combination with [clearIndexedDbPersistence()](./firestore_.md#clearindexeddbpersistence) to ensure that all local state is destroyed between test runs. + +Signature: + +```typescript +export declare function terminate(firestore: Firestore): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | The Firestore instance to terminate. | + +Returns: + +Promise<void> + +A `Promise` that is resolved when the instance has been successfully terminated. + +## writeBatch() + +Creates a write batch, used for performing multiple writes as a single atomic operation. The maximum number of writes allowed in a single WriteBatch is 500. + +The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. + +Signature: + +```typescript +export declare function writeBatch(firestore: Firestore): WriteBatch; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_lite.firestore.md#firestore_class) | | + +Returns: + +[WriteBatch](./firestore_lite.writebatch.md#writebatch_class) + +A `WriteBatch` that can be used to atomically execute multiple writes. + +## deleteField() + +Returns a sentinel for use with [updateDoc()](./firestore_lite.md#updatedoc) or [setDoc()](./firestore_lite.md#setdoc) with `{merge: true}` to mark a field for deletion. + +Signature: + +```typescript +export declare function deleteField(): FieldValue; +``` +Returns: + +[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) + +## documentId() + +Returns a special sentinel `FieldPath` to refer to the ID of a document. It can be used in queries to sort or filter by the document ID. + +Signature: + +```typescript +export declare function documentId(): FieldPath; +``` +Returns: + +[FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) + +## getFirestore() + +Returns the existing default [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: + +```typescript +export declare function getFirestore(): Firestore; +``` +Returns: + +[Firestore](./firestore_lite.firestore.md#firestore_class) + +The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. + +## 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. + +Signature: + +```typescript +export declare function serverTimestamp(): FieldValue; +``` +Returns: + +[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) + +## 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. + +Signature: + +```typescript +export declare function arrayRemove(...elements: unknown[]): FieldValue; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| elements | unknown\[\] | The elements to remove from the array. | + +Returns: + +[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) + +The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()` + +## 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. + +Signature: + +```typescript +export declare function arrayUnion(...elements: unknown[]): FieldValue; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| elements | unknown\[\] | The elements to union into the array. | + +Returns: + +[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) + +The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()`. + +## orderBy() + +Creates a [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class) that sorts the query result by the specified field, optionally in descending order instead of ascending. + +Note: Documents that do not contain the specified field will not be present in the query result. + +Signature: + +```typescript +export declare function orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDirection): QueryOrderByConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldPath | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The field to sort by. | +| directionStr | [OrderByDirection](./firestore_lite.md#orderbydirection) | Optional direction to sort by ('asc' or 'desc'). If not specified, order will be ascending. | + +Returns: + +[QueryOrderByConstraint](./firestore_lite.queryorderbyconstraint.md#queryorderbyconstraint_class) + +The created [QueryOrderByConstraint](./firestore_.queryorderbyconstraint.md#queryorderbyconstraint_class). + +## where() + +Creates a [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) that enforces that documents must contain the specified field and that the value should satisfy the relation constraint provided. + +Signature: + +```typescript +export declare function where(fieldPath: string | FieldPath, opStr: WhereFilterOp, value: unknown): QueryFieldFilterConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldPath | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The path to compare | +| opStr | [WhereFilterOp](./firestore_lite.md#wherefilterop) | The operation string (e.g "&lt;", "&lt;=", "==", "&lt;", "&lt;=", "!="). | +| value | unknown | The value for comparison | + +Returns: + +[QueryFieldFilterConstraint](./firestore_lite.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class) + +The created [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class). + +## endAt() + +Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. + +Signature: + +```typescript +export declare function endAt(...fieldValues: unknown[]): QueryEndAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldValues | unknown\[\] | The field values to end this query at, in order of the query's order by. | + +Returns: + +[QueryEndAtConstraint](./firestore_lite.queryendatconstraint.md#queryendatconstraint_class) + +A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` + +## endBefore() + +Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. + +Signature: + +```typescript +export declare function endBefore(...fieldValues: unknown[]): QueryEndAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldValues | unknown\[\] | The field values to end this query before, in order of the query's order by. | + +Returns: + +[QueryEndAtConstraint](./firestore_lite.queryendatconstraint.md#queryendatconstraint_class) + +A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` + +## startAfter() + +Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. + +Signature: + +```typescript +export declare function startAfter(...fieldValues: unknown[]): QueryStartAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldValues | unknown\[\] | The field values to start this query after, in order of the query's order by. | + +Returns: + +[QueryStartAtConstraint](./firestore_lite.querystartatconstraint.md#querystartatconstraint_class) + +A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()` + +## startAt() + +Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. + +Signature: + +```typescript +export declare function startAt(...fieldValues: unknown[]): QueryStartAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| fieldValues | unknown\[\] | The field values to start this query at, in order of the query's order by. | + +Returns: + +[QueryStartAtConstraint](./firestore_lite.querystartatconstraint.md#querystartatconstraint_class) + +A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()`. + +## aggregateQuerySnapshotEqual() + +Compares two `AggregateQuerySnapshot` instances for equality. + +Two `AggregateQuerySnapshot` instances are considered "equal" if they have underlying queries that compare equal, and the same data. + +Signature: + +```typescript +export declare function aggregateQuerySnapshotEqual(left: AggregateQuerySnapshot, right: AggregateQuerySnapshot): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| left | [AggregateQuerySnapshot](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<T> | The first AggregateQuerySnapshot to compare. | +| right | [AggregateQuerySnapshot](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<T> | The second AggregateQuerySnapshot to compare. | + +Returns: + +boolean + +`true` if the objects are "equal", as defined above, or `false` otherwise. + +## queryEqual() + +Returns true if the provided queries point to the same collection and apply the same constraints. + +Signature: + +```typescript +export declare function queryEqual(left: Query, right: Query): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| left | [Query](./firestore_lite.query.md#query_class)<T> | A Query to compare. | +| right | [Query](./firestore_lite.query.md#query_class)<T> | A Query to compare. | + +Returns: + +boolean + +true if the references point to the same location in the same Firestore database. + +## refEqual() + +Returns true if the provided references are equal. + +Signature: + +```typescript +export declare function refEqual(left: DocumentReference | CollectionReference, right: DocumentReference | CollectionReference): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| left | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> \| [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | A reference to compare. | +| right | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> \| [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | A reference to compare. | + +Returns: + +boolean + +true if the references point to the same location in the same Firestore database. + +## snapshotEqual() + +Returns true if the provided snapshots are equal. + +Signature: + +```typescript +export declare function snapshotEqual(left: DocumentSnapshot | QuerySnapshot, right: DocumentSnapshot | QuerySnapshot): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| left | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<T> \| [QuerySnapshot](./firestore_lite.querysnapshot.md#querysnapshot_class)<T> | A snapshot to compare. | +| right | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<T> \| [QuerySnapshot](./firestore_lite.querysnapshot.md#querysnapshot_class)<T> | A snapshot to compare. | + +Returns: + +boolean + +true if the snapshots are equal. + +## limit() + +Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the first matching documents. + +Signature: + +```typescript +export declare function limit(limit: number): QueryLimitConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| limit | number | The maximum number of items to return. | + +Returns: + +[QueryLimitConstraint](./firestore_lite.querylimitconstraint.md#querylimitconstraint_class) + +The created [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class). + +## limitToLast() + +Creates a [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class) that only returns the last matching documents. + +You must specify at least one `orderBy` clause for `limitToLast` queries, otherwise an exception will be thrown during execution. + +Signature: + +```typescript +export declare function limitToLast(limit: number): QueryLimitConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| limit | number | The maximum number of items to return. | + +Returns: + +[QueryLimitConstraint](./firestore_lite.querylimitconstraint.md#querylimitconstraint_class) + +The created [QueryLimitConstraint](./firestore_.querylimitconstraint.md#querylimitconstraint_class). + +## setLogLevel() + +Sets the verbosity of Cloud Firestore logs (debug, error, or silent). + +Signature: + +```typescript +export declare function setLogLevel(logLevel: LogLevel): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| logLevel | LogLevel | The verbosity you set for activity and error logging. Can be any of the following values:
  • debug for the most verbose logging level, primarily for debugging.
  • error to log errors only.
  • silent to turn off logging.
| + +Returns: + +void + +## increment() + +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 increment the field's current value by the given value. + +If either the operand or the current field value uses floating point precision, all arithmetic follows IEEE 754 semantics. If both values are integers, values outside of JavaScript's safe number range (`Number.MIN_SAFE_INTEGER` to `Number.MAX_SAFE_INTEGER`) are also subject to precision loss. Furthermore, once processed by the Firestore backend, all integer operations are capped between -2^63 and 2^63-1. + +If the current field value is not of type `number`, or if the field does not yet exist, the transformation sets the field to the given value. + +Signature: + +```typescript +export declare function increment(n: number): FieldValue; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| n | number | The value to increment by. | + +Returns: + +[FieldValue](./firestore_lite.fieldvalue.md#fieldvalue_class) + +The `FieldValue` sentinel for use in a call to `setDoc()` or `updateDoc()` + +## getCount() + +Calculates the number of documents in the result set of the given query, without actually downloading the documents. + +Using this function to count the documents is efficient because only the final count, not the documents' data, is downloaded. This function can even count the documents if the result set would be prohibitively large to download entirely (e.g. thousands of documents). + +Signature: + +```typescript +export declare function getCount(query: Query): Promise; +}>>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./firestore_lite.query.md#query_class)<unknown> | The query whose result set size to calculate. | + +Returns: + +Promise<[AggregateQuerySnapshot](./firestore_lite.aggregatequerysnapshot.md#aggregatequerysnapshot_class)<{ count: [AggregateField](./firestore_lite.aggregatefield.md#aggregatefield_class)<number>; }>> + +A Promise that will be resolved with the count; the count can be retrieved from `snapshot.data().count`, where `snapshot` is the `AggregateQuerySnapshot` to which the returned Promise resolves. + +## getDocs() + +Executes the query and returns the results as a [QuerySnapshot](./firestore_.querysnapshot.md#querysnapshot_class). + +All queries are executed directly by the server, even if the the query was previously executed. Recent modifications are only reflected in the retrieved results if they have already been applied by the backend. If the client is offline, the operation fails. To see previously cached result and local modifications, use the full Firestore SDK. + +Signature: + +```typescript +export declare function getDocs(query: Query): Promise>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./firestore_lite.query.md#query_class)<T> | The Query to execute. | + +Returns: + +Promise<[QuerySnapshot](./firestore_lite.querysnapshot.md#querysnapshot_class)<T>> + +A Promise that will be resolved with the results of the query. + +## query() + +Creates a new immutable instance of [Query](./firestore_.query.md#query_class) that is extended to also include additional query constraints. + +Signature: + +```typescript +export declare function query(query: Query, ...queryConstraints: QueryConstraint[]): Query; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| query | [Query](./firestore_lite.query.md#query_class)<T> | The [Query](./firestore_.query.md#query_class) instance to use as a base for the new constraints. | +| queryConstraints | [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class)\[\] | The list of [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class)s to apply. | + +Returns: + +[Query](./firestore_lite.query.md#query_class)<T> + +## Exceptions + +if any of the provided query constraints cannot be combined with the existing or new constraints. + +## addDoc() + +Add a new document to specified `CollectionReference` with the given data, assigning it a document ID automatically. + +The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. + +Signature: + +```typescript +export declare function addDoc(reference: CollectionReference, data: WithFieldValue): Promise>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | A reference to the collection to add this document to. | +| data | [WithFieldValue](./firestore_lite.md#withfieldvalue)<T> | An Object containing the data for the new document. | + +Returns: + +Promise<[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T>> + +A `Promise` resolved with a `DocumentReference` pointing to the newly created document after it has been written to the backend. + +## Exceptions + +Error - If the provided input is not a valid Firestore document. + +## collection() + +Gets a `CollectionReference` instance that refers to a subcollection of `reference` at the the specified relative path. + +Signature: + +```typescript +export declare function collection(reference: CollectionReference, path: string, ...pathSegments: string[]): CollectionReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<unknown> | A reference to a collection. | +| path | string | A slash-separated path to a collection. | +| pathSegments | string\[\] | Additional path segments to apply relative to the first argument. | + +Returns: + +[CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> + +The `CollectionReference` instance. + +## Exceptions + +If the final path has an even number of segments and does not point to a collection. + +## collection() + +Gets a `CollectionReference` instance that refers to a subcollection of `reference` at the the specified relative path. + +Signature: + +```typescript +export declare function collection(reference: DocumentReference, path: string, ...pathSegments: string[]): CollectionReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class) | A reference to a Firestore document. | +| path | string | A slash-separated path to a collection. | +| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | + +Returns: + +[CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> + +The `CollectionReference` instance. + +## Exceptions + +If the final path has an even number of segments and does not point to a collection. + +## deleteDoc() + +Deletes the document referred to by the specified `DocumentReference`. + +The deletion will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the delete fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. + +Signature: + +```typescript +export declare function deleteDoc(reference: DocumentReference): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to the document to delete. | + +Returns: + +Promise<void> + +A `Promise` resolved once the document has been successfully deleted from the backend. + +## doc() + +Gets a `DocumentReference` instance that refers to a document within `reference` at the specified relative path. If no path is specified, an automatically-generated unique ID will be used for the returned `DocumentReference`. + +Signature: + +```typescript +export declare function doc(reference: CollectionReference, path?: string, ...pathSegments: string[]): DocumentReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [CollectionReference](./firestore_lite.collectionreference.md#collectionreference_class)<T> | A reference to a collection. | +| path | string | A slash-separated path to a document. Has to be omitted to use auto-genrated IDs. | +| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | + +Returns: + +[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> + +The `DocumentReference` instance. + +## Exceptions + +If the final path has an odd number of segments and does not point to a document. + +## doc() + +Gets a `DocumentReference` instance that refers to a document within `reference` at the specified relative path. + +Signature: + +```typescript +export declare function doc(reference: DocumentReference, path: string, ...pathSegments: string[]): DocumentReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to a Firestore document. | +| path | string | A slash-separated path to a document. | +| pathSegments | string\[\] | Additional path segments that will be applied relative to the first argument. | + +Returns: + +[DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> + +The `DocumentReference` instance. + +## Exceptions + +If the final path has an odd number of segments and does not point to a document. + +## getDoc() + +Reads the document referred to by the specified document reference. + +All documents are directly fetched from the server, even if the document was previously read or modified. Recent modifications are only reflected in the retrieved `DocumentSnapshot` if they have already been applied by the backend. If the client is offline, the read fails. If you like to use caching or see local modifications, please use the full Firestore SDK. + +Signature: + +```typescript +export declare function getDoc(reference: DocumentReference): Promise>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | The reference of the document to fetch. | + +Returns: + +Promise<[DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<T>> + +A Promise resolved with a `DocumentSnapshot` containing the current document contents. + +## setDoc() + +Writes to the document referred to by the specified `DocumentReference`. If the document does not yet exist, it will be created. + +The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. + +Signature: + +```typescript +export declare function setDoc(reference: DocumentReference, data: WithFieldValue): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to write. | +| data | [WithFieldValue](./firestore_lite.md#withfieldvalue)<T> | A map of the fields and values for the document. | + +Returns: + +Promise<void> + +A `Promise` resolved once the data has been successfully written to the backend. + +## Exceptions + +Error - If the provided input is not a valid Firestore document. + +## setDoc() + +Writes to the document referred to by the specified `DocumentReference`. If the document does not yet exist, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. + +The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. + +Signature: + +```typescript +export declare function setDoc(reference: DocumentReference, data: PartialWithFieldValue, options: SetOptions): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to write. | +| data | [PartialWithFieldValue](./firestore_lite.md#partialwithfieldvalue)<T> | A map of the fields and values for the document. | +| options | [SetOptions](./firestore_lite.md#setoptions) | An object to configure the set behavior. | + +Returns: + +Promise<void> + +A `Promise` resolved once the data has been successfully written to the backend. + +## Exceptions + +Error - If the provided input is not a valid Firestore document. + +## updateDoc() + +Updates fields in the document referred to by the specified `DocumentReference`. The update will fail if applied to a document that does not exist. + +The result of this update will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the update fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. + +Signature: + +```typescript +export declare function updateDoc(reference: DocumentReference, data: UpdateData): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to update. | +| data | [UpdateData](./firestore_lite.md#updatedata)<T> | An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document. | + +Returns: + +Promise<void> + +A `Promise` resolved once the data has been successfully written to the backend. + +## Exceptions + +Error - If the provided input is not valid Firestore data. + +## updateDoc() + +Updates fields in the document referred to by the specified `DocumentReference` The update will fail if applied to a document that does not exist. + +Nested fields can be updated by providing dot-separated field path strings or by providing `FieldPath` objects. + +The result of this update will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the update fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. + +Signature: + +```typescript +export declare function updateDoc(reference: DocumentReference, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| reference | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to the document to update. | +| field | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The first field to update. | +| value | unknown | The first value. | +| moreFieldsAndValues | unknown\[\] | Additional key value pairs. | + +Returns: + +Promise<void> + +A `Promise` resolved once the data has been successfully written to the backend. + +## Exceptions + +Error - If the provided input is not valid Firestore data. + +## endAt() + +Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end at the provided document (inclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. + +Signature: + +```typescript +export declare function endAt(snapshot: DocumentSnapshot): QueryEndAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| snapshot | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to end at. | + +Returns: + +[QueryEndAtConstraint](./firestore_lite.queryendatconstraint.md#queryendatconstraint_class) + +A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` + +## endBefore() + +Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. + +Signature: + +```typescript +export declare function endBefore(snapshot: DocumentSnapshot): QueryEndAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| snapshot | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to end before. | + +Returns: + +[QueryEndAtConstraint](./firestore_lite.queryendatconstraint.md#queryendatconstraint_class) + +A [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) to pass to `query()` + +## startAfter() + +Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query. + +Signature: + +```typescript +export declare function startAfter(snapshot: DocumentSnapshot): QueryStartAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| snapshot | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to start after. | + +Returns: + +[QueryStartAtConstraint](./firestore_lite.querystartatconstraint.md#querystartatconstraint_class) + +A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()` + +## startAt() + +Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the `orderBy` of this query. + +Signature: + +```typescript +export declare function startAt(snapshot: DocumentSnapshot): QueryStartAtConstraint; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| snapshot | [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<unknown> | The snapshot of the document to start at. | + +Returns: + +[QueryStartAtConstraint](./firestore_lite.querystartatconstraint.md#querystartatconstraint_class) + +A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()`. + +## AddPrefixToKeys + +Returns a new map where every key is prefixed with the outer key appended to a dot. + +Signature: + +```typescript +export declare type AddPrefixToKeys> = { + [K in keyof T & string as `${Prefix}.${K}`]+?: T[K]; +}; +``` + +## AggregateFieldType + +The union of all `AggregateField` types that are supported by Firestore. + +Signature: + +```typescript +export declare type AggregateFieldType = AggregateField; +``` + +## AggregateSpecData + +A type whose keys are taken from an `AggregateSpec`, and whose values are the result of the aggregation performed by the corresponding `AggregateField` from the input `AggregateSpec`. + +Signature: + +```typescript +export declare type AggregateSpecData = { + [P in keyof T]: T[P] extends AggregateField ? U : never; +}; +``` + +## ChildUpdateFields + +Helper for calculating the nested fields for a given type T1. This is needed to distribute union types such as `undefined | {...}` (happens for optional props) or `{a: A} | {b: B}`. + +In this use case, `V` is used to distribute the union types of `T[K]` on `Record`, since `T[K]` is evaluated as an expression and not distributed. + +See https://www.typescriptlang.org/docs/handbook/advanced-types.html\#distributive-conditional-types + +Signature: + +```typescript +export declare type ChildUpdateFields = V extends Record ? AddPrefixToKeys> : never; +``` + +## FirestoreErrorCode + +The set of Firestore status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.md + +Possible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (e.g. an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation. + +Signature: + +```typescript +export declare type FirestoreErrorCode = 'cancelled' | 'unknown' | 'invalid-argument' | 'deadline-exceeded' | 'not-found' | 'already-exists' | 'permission-denied' | 'resource-exhausted' | 'failed-precondition' | 'aborted' | 'out-of-range' | 'unimplemented' | 'internal' | 'unavailable' | 'data-loss' | 'unauthenticated'; +``` + +## NestedUpdateFields + +For each field (e.g. 'bar'), find all nested keys (e.g. {'bar.baz': T1, 'bar.qux': T2}). Intersect them together to make a single map containing all possible keys that are all marked as optional + +Signature: + +```typescript +export declare type NestedUpdateFields> = UnionToIntersection<{ + [K in keyof T & string]: ChildUpdateFields; +}[keyof T & string]>; +``` + +## OrderByDirection + +The direction of a [orderBy()](./firestore_.md#orderby) clause is specified as 'desc' or 'asc' (descending or ascending). + +Signature: + +```typescript +export declare type OrderByDirection = 'desc' | 'asc'; +``` + +## PartialWithFieldValue + +Similar to Typescript's `Partial`, but allows nested fields to be omitted and FieldValues to be passed in as property values. + +Signature: + +```typescript +export declare type PartialWithFieldValue = Partial | (T extends Primitive ? T : T extends {} ? { + [K in keyof T]?: PartialWithFieldValue | FieldValue; +} : never); +``` + +## Primitive + +Primitive types. + +Signature: + +```typescript +export declare type Primitive = string | number | boolean | undefined | null; +``` + +## QueryConstraintType + +Describes the different query constraints available in this SDK. + +Signature: + +```typescript +export declare type QueryConstraintType = 'where' | 'orderBy' | 'limit' | 'limitToLast' | 'startAt' | 'startAfter' | 'endAt' | 'endBefore'; +``` + +## QueryNonFilterConstraint + +`QueryNonFilterConstraint` is a helper union type that represents QueryConstraints which are used to narrow or order the set of documents, but that do not explicitly filter on a document field. `QueryNonFilterConstraint`s are created by invoking [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains the `QueryConstraint`. + +Signature: + +```typescript +export declare type QueryNonFilterConstraint = QueryOrderByConstraint | QueryLimitConstraint | QueryStartAtConstraint | QueryEndAtConstraint; +``` + +## SetOptions + +An options object that configures the behavior of [setDoc()](./firestore_lite.md#setdoc), and calls. These calls can be configured to perform granular merges instead of overwriting the target documents in their entirety by providing a `SetOptions` with `merge: true`. + +Signature: + +```typescript +export declare type SetOptions = { + readonly merge?: boolean; +} | { + readonly mergeFields?: Array; +}; +``` + +## UnionToIntersection + +Given a union type `U = T1 | T2 | ...`, returns an intersected type `(T1 & T2 & ...)`. + +Uses distributive conditional types and inference from conditional types. This works because multiple candidates for the same type variable in contra-variant positions causes an intersection type to be inferred. https://www.typescriptlang.org/docs/handbook/advanced-types.html\#type-inference-in-conditional-types https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection-type + +Signature: + +```typescript +export declare type UnionToIntersection = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never; +``` + +## UpdateData + +Update data (for use with [updateDoc()](./firestore_.md#updatedoc)) that consists of field paths (e.g. 'foo' or 'foo.baz') mapped to values. Fields that contain dots reference nested fields within the document. FieldValues can be passed in as property values. + +Signature: + +```typescript +export declare type UpdateData = T extends Primitive ? T : T extends {} ? { + [K in keyof T]?: UpdateData | FieldValue; +} & NestedUpdateFields : Partial; +``` + +## WhereFilterOp + +Filter conditions in a [where()](./firestore_.md#where) clause are specified using the strings '&lt;', '&lt;=', '==', '!=', '&gt;=', '&gt;', 'array-contains', 'in', 'array-contains-any', and 'not-in'. + +Signature: + +```typescript +export declare type WhereFilterOp = '<' | '<=' | '==' | '!=' | '>=' | '>' | 'array-contains' | 'in' | 'array-contains-any' | 'not-in'; +``` + +## WithFieldValue + +Allows FieldValues to be passed in as a property value while maintaining type safety. + +Signature: + +```typescript +export declare type WithFieldValue = T | (T extends Primitive ? T : T extends {} ? { + [K in keyof T]: WithFieldValue | FieldValue; +} : never); +``` diff --git a/docs-devsite/firestore_lite.query.md b/docs-devsite/firestore_lite.query.md new file mode 100644 index 00000000000..f2eac7560dc --- /dev/null +++ b/docs-devsite/firestore_lite.query.md @@ -0,0 +1,125 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Query class +A `Query` refers to a query which you can read or listen to. You can also construct refined `Query` objects by adding filters and ordering. + +Signature: + +```typescript +export declare class Query +``` + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)()](./firestore_lite.query.md#queryconstructor) | | Constructs a new instance of the Query class | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [converter](./firestore_lite.query.md#queryconverter) | | [FirestoreDataConverter](./firestore_lite.firestoredataconverter.md#firestoredataconverter_interface)<T> \| null | If provided, the FirestoreDataConverter associated with this instance. | +| [firestore](./firestore_lite.query.md#queryfirestore) | | [Firestore](./firestore_lite.firestore.md#firestore_class) | The Firestore instance for the Firestore database (useful for performing transactions, etc.). | +| [type](./firestore_lite.query.md#querytype) | | 'query' \| 'collection' | The type of this Firestore reference. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [withConverter(converter)](./firestore_lite.query.md#querywithconverter) | | Removes the current converter. | +| [withConverter(converter)](./firestore_lite.query.md#querywithconverter) | | Applies a custom data converter to this query, allowing you to use your own custom model objects with Firestore. When you call [getDocs()](./firestore_.md#getdocs) with the returned query, the provided converter will convert between Firestore data and your custom type U. | + +## Query.(constructor) + +Constructs a new instance of the `Query` class + +Signature: + +```typescript +protected constructor(); +``` + +## Query.converter + +If provided, the `FirestoreDataConverter` associated with this instance. + +Signature: + +```typescript +readonly converter: FirestoreDataConverter | null; +``` + +## Query.firestore + +The `Firestore` instance for the Firestore database (useful for performing transactions, etc.). + +Signature: + +```typescript +readonly firestore: Firestore; +``` + +## Query.type + +The type of this Firestore reference. + +Signature: + +```typescript +readonly type: 'query' | 'collection'; +``` + +## Query.withConverter() + +Removes the current converter. + +Signature: + +```typescript +withConverter(converter: null): Query; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| converter | null | null removes the current converter. | + +Returns: + +[Query](./firestore_lite.query.md#query_class)<[DocumentData](./firestore_lite.documentdata.md#documentdata_interface)> + +A `Query` that does not use a converter. + +## Query.withConverter() + +Applies a custom data converter to this query, allowing you to use your own custom model objects with Firestore. When you call [getDocs()](./firestore_.md#getdocs) with the returned query, the provided converter will convert between Firestore data and your custom type `U`. + +Signature: + +```typescript +withConverter(converter: FirestoreDataConverter): Query; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| converter | [FirestoreDataConverter](./firestore_lite.firestoredataconverter.md#firestoredataconverter_interface)<U> | Converts objects to and from Firestore. | + +Returns: + +[Query](./firestore_lite.query.md#query_class)<U> + +A `Query` that uses the provided converter. + diff --git a/docs-devsite/firestore_lite.queryconstraint.md b/docs-devsite/firestore_lite.queryconstraint.md new file mode 100644 index 00000000000..dae8d5f0069 --- /dev/null +++ b/docs-devsite/firestore_lite.queryconstraint.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryConstraint class +A `QueryConstraint` is used to narrow the set of documents returned by a Firestore query. `QueryConstraint`s are created by invoking [where()](./firestore_.md#where), [orderBy()](./firestore_.md#orderby), , , , , [limit()](./firestore_.md#limit), [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryConstraint`. + +Signature: + +```typescript +export declare abstract class QueryConstraint +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_lite.queryconstraint.md#queryconstrainttype) | | [QueryConstraintType](./firestore_lite.md#queryconstrainttype) | The type of this query constraint | + +## QueryConstraint.type + +The type of this query constraint + +Signature: + +```typescript +abstract readonly type: QueryConstraintType; +``` diff --git a/docs-devsite/firestore_lite.querydocumentsnapshot.md b/docs-devsite/firestore_lite.querydocumentsnapshot.md new file mode 100644 index 00000000000..356d7ecaeed --- /dev/null +++ b/docs-devsite/firestore_lite.querydocumentsnapshot.md @@ -0,0 +1,45 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryDocumentSnapshot class +A `QueryDocumentSnapshot` contains data read from a document in your Firestore database as part of a query. The document is guaranteed to exist and its data can be extracted with `.data()` or `.get()` to get a specific field. + +A `QueryDocumentSnapshot` offers the same API surface as a `DocumentSnapshot`. Since query results contain only existing documents, the `exists` property will always be true and `data()` will never return 'undefined'. + +Signature: + +```typescript +export declare class QueryDocumentSnapshot extends DocumentSnapshot +``` +Extends: [DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<T> + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [data()](./firestore_lite.querydocumentsnapshot.md#querydocumentsnapshotdata) | | Retrieves all fields in the document as an Object. | + +## QueryDocumentSnapshot.data() + +Retrieves all fields in the document as an `Object`. + +Signature: + +```typescript +/** @override */ +data(): T; +``` +Returns: + +T + +An `Object` containing all fields in the document. + diff --git a/docs-devsite/firestore_lite.queryendatconstraint.md b/docs-devsite/firestore_lite.queryendatconstraint.md new file mode 100644 index 00000000000..7f999a414b6 --- /dev/null +++ b/docs-devsite/firestore_lite.queryendatconstraint.md @@ -0,0 +1,36 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryEndAtConstraint class +A `QueryEndAtConstraint` is used to exclude documents from the end of a result set returned by a Firestore query. `QueryEndAtConstraint`s are created by invoking [endAt()](./firestore_.md#endat) or [endBefore()](./firestore_.md#endbefore) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryEndAtConstraint`. + +Signature: + +```typescript +export declare class QueryEndAtConstraint extends QueryConstraint +``` +Extends: [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_lite.queryendatconstraint.md#queryendatconstrainttype) | | 'endBefore' \| 'endAt' | The type of this query constraint | + +## QueryEndAtConstraint.type + +The type of this query constraint + +Signature: + +```typescript +readonly type: 'endBefore' | 'endAt'; +``` diff --git a/docs-devsite/firestore_lite.queryfieldfilterconstraint.md b/docs-devsite/firestore_lite.queryfieldfilterconstraint.md new file mode 100644 index 00000000000..81c1509223d --- /dev/null +++ b/docs-devsite/firestore_lite.queryfieldfilterconstraint.md @@ -0,0 +1,36 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryFieldFilterConstraint class +A `QueryFieldFilterConstraint` is used to narrow the set of documents returned by a Firestore query by filtering on one or more document fields. `QueryFieldFilterConstraint`s are created by invoking [where()](./firestore_.md#where) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryFieldFilterConstraint`. + +Signature: + +```typescript +export declare class QueryFieldFilterConstraint extends QueryConstraint +``` +Extends: [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_lite.queryfieldfilterconstraint.md#queryfieldfilterconstrainttype) | | (not declared) | The type of this query constraint | + +## QueryFieldFilterConstraint.type + +The type of this query constraint + +Signature: + +```typescript +readonly type = "where"; +``` diff --git a/docs-devsite/firestore_lite.querylimitconstraint.md b/docs-devsite/firestore_lite.querylimitconstraint.md new file mode 100644 index 00000000000..82218279e34 --- /dev/null +++ b/docs-devsite/firestore_lite.querylimitconstraint.md @@ -0,0 +1,36 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryLimitConstraint class +A `QueryLimitConstraint` is used to limit the number of documents returned by a Firestore query. `QueryLimitConstraint`s are created by invoking [limit()](./firestore_.md#limit) or [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryLimitConstraint`. + +Signature: + +```typescript +export declare class QueryLimitConstraint extends QueryConstraint +``` +Extends: [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_lite.querylimitconstraint.md#querylimitconstrainttype) | | 'limit' \| 'limitToLast' | The type of this query constraint | + +## QueryLimitConstraint.type + +The type of this query constraint + +Signature: + +```typescript +readonly type: 'limit' | 'limitToLast'; +``` diff --git a/docs-devsite/firestore_lite.queryorderbyconstraint.md b/docs-devsite/firestore_lite.queryorderbyconstraint.md new file mode 100644 index 00000000000..b5a28ed3e9a --- /dev/null +++ b/docs-devsite/firestore_lite.queryorderbyconstraint.md @@ -0,0 +1,38 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryOrderByConstraint class +A `QueryOrderByConstraint` is used to sort the set of documents returned by a Firestore query. `QueryOrderByConstraint`s are created by invoking [orderBy()](./firestore_.md#orderby) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryOrderByConstraint`. + +Note: Documents that do not contain the orderBy field will not be present in the query result. + +Signature: + +```typescript +export declare class QueryOrderByConstraint extends QueryConstraint +``` +Extends: [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_lite.queryorderbyconstraint.md#queryorderbyconstrainttype) | | (not declared) | The type of this query constraint | + +## QueryOrderByConstraint.type + +The type of this query constraint + +Signature: + +```typescript +readonly type = "orderBy"; +``` diff --git a/docs-devsite/firestore_lite.querysnapshot.md b/docs-devsite/firestore_lite.querysnapshot.md new file mode 100644 index 00000000000..8e805af948d --- /dev/null +++ b/docs-devsite/firestore_lite.querysnapshot.md @@ -0,0 +1,96 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QuerySnapshot class +A `QuerySnapshot` contains zero or more `DocumentSnapshot` objects representing the results of a query. The documents can be accessed as an array via the `docs` property or enumerated using the `forEach` method. The number of documents can be determined via the `empty` and `size` properties. + +Signature: + +```typescript +export declare class QuerySnapshot +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [docs](./firestore_lite.querysnapshot.md#querysnapshotdocs) | | Array<[QueryDocumentSnapshot](./firestore_lite.querydocumentsnapshot.md#querydocumentsnapshot_class)<T>> | An array of all the documents in the QuerySnapshot. | +| [empty](./firestore_lite.querysnapshot.md#querysnapshotempty) | | boolean | True if there are no documents in the QuerySnapshot. | +| [query](./firestore_lite.querysnapshot.md#querysnapshotquery) | | [Query](./firestore_lite.query.md#query_class)<T> | The query on which you called [getDocs()](./firestore_.md#getdocs) in order to get this QuerySnapshot. | +| [size](./firestore_lite.querysnapshot.md#querysnapshotsize) | | number | The number of documents in the QuerySnapshot. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [forEach(callback, thisArg)](./firestore_lite.querysnapshot.md#querysnapshotforeach) | | Enumerates all of the documents in the QuerySnapshot. | + +## QuerySnapshot.docs + +An array of all the documents in the `QuerySnapshot`. + +Signature: + +```typescript +get docs(): Array>; +``` + +## QuerySnapshot.empty + +True if there are no documents in the `QuerySnapshot`. + +Signature: + +```typescript +get empty(): boolean; +``` + +## QuerySnapshot.query + +The query on which you called [getDocs()](./firestore_.md#getdocs) in order to get this `QuerySnapshot`. + +Signature: + +```typescript +readonly query: Query; +``` + +## QuerySnapshot.size + +The number of documents in the `QuerySnapshot`. + +Signature: + +```typescript +get size(): number; +``` + +## QuerySnapshot.forEach() + +Enumerates all of the documents in the `QuerySnapshot`. + +Signature: + +```typescript +forEach(callback: (result: QueryDocumentSnapshot) => void, thisArg?: unknown): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| callback | (result: [QueryDocumentSnapshot](./firestore_lite.querydocumentsnapshot.md#querydocumentsnapshot_class)<T>) => void | A callback to be called with a QueryDocumentSnapshot for each document in the snapshot. | +| thisArg | unknown | The this binding for the callback. | + +Returns: + +void + diff --git a/docs-devsite/firestore_lite.querystartatconstraint.md b/docs-devsite/firestore_lite.querystartatconstraint.md new file mode 100644 index 00000000000..08d6ba15103 --- /dev/null +++ b/docs-devsite/firestore_lite.querystartatconstraint.md @@ -0,0 +1,36 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# QueryStartAtConstraint class +A `QueryStartAtConstraint` is used to exclude documents from the start of a result set returned by a Firestore query. `QueryStartAtConstraint`s are created by invoking [startAt()](./firestore_.md#startat) or [startAfter()](./firestore_.md#startafter) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this `QueryStartAtConstraint`. + +Signature: + +```typescript +export declare class QueryStartAtConstraint extends QueryConstraint +``` +Extends: [QueryConstraint](./firestore_lite.queryconstraint.md#queryconstraint_class) + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_lite.querystartatconstraint.md#querystartatconstrainttype) | | 'startAt' \| 'startAfter' | The type of this query constraint | + +## QueryStartAtConstraint.type + +The type of this query constraint + +Signature: + +```typescript +readonly type: 'startAt' | 'startAfter'; +``` diff --git a/docs-devsite/firestore_lite.settings.md b/docs-devsite/firestore_lite.settings.md new file mode 100644 index 00000000000..ae792a0fc6d --- /dev/null +++ b/docs-devsite/firestore_lite.settings.md @@ -0,0 +1,57 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Settings interface +Specifies custom configurations for your Cloud Firestore instance. You must set these before invoking any other methods. + +Signature: + +```typescript +export declare interface Settings +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [host](./firestore_lite.settings.md#settingshost) | string | The hostname to connect to. | +| [ignoreUndefinedProperties](./firestore_lite.settings.md#settingsignoreundefinedproperties) | boolean | Whether to skip nested properties that are set to undefined during object serialization. If set to true, these properties are skipped and not written to Firestore. If set to false or omitted, the SDK throws an exception when it encounters properties of type undefined. | +| [ssl](./firestore_lite.settings.md#settingsssl) | boolean | Whether to use SSL when connecting. | + +## Settings.host + +The hostname to connect to. + +Signature: + +```typescript +host?: string; +``` + +## Settings.ignoreUndefinedProperties + +Whether to skip nested properties that are set to `undefined` during object serialization. If set to `true`, these properties are skipped and not written to Firestore. If set to `false` or omitted, the SDK throws an exception when it encounters properties of type `undefined`. + +Signature: + +```typescript +ignoreUndefinedProperties?: boolean; +``` + +## Settings.ssl + +Whether to use SSL when connecting. + +Signature: + +```typescript +ssl?: boolean; +``` diff --git a/docs-devsite/firestore_lite.timestamp.md b/docs-devsite/firestore_lite.timestamp.md new file mode 100644 index 00000000000..7b18abc69db --- /dev/null +++ b/docs-devsite/firestore_lite.timestamp.md @@ -0,0 +1,243 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Timestamp class +A `Timestamp` represents a point in time independent of any time zone or calendar, represented as seconds and fractions of seconds at nanosecond resolution in UTC Epoch time. + +It is encoded using the Proleptic Gregorian Calendar which extends the Gregorian calendar backwards to year one. It is encoded assuming all minutes are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. + +For examples and further specifications, refer to the [Timestamp definition](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto). + +Signature: + +```typescript +export declare class Timestamp +``` + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(seconds, nanoseconds)](./firestore_lite.timestamp.md#timestampconstructor) | | Creates a new timestamp. | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [nanoseconds](./firestore_lite.timestamp.md#timestampnanoseconds) | | number | The fractions of a second at nanosecond resolution.\* | +| [seconds](./firestore_lite.timestamp.md#timestampseconds) | | number | The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [fromDate(date)](./firestore_lite.timestamp.md#timestampfromdate) | static | Creates a new timestamp from the given date. | +| [fromMillis(milliseconds)](./firestore_lite.timestamp.md#timestampfrommillis) | static | Creates a new timestamp from the given number of milliseconds. | +| [isEqual(other)](./firestore_lite.timestamp.md#timestampisequal) | | Returns true if this Timestamp is equal to the provided one. | +| [now()](./firestore_lite.timestamp.md#timestampnow) | static | Creates a new timestamp with the current date, with millisecond precision. | +| [toDate()](./firestore_lite.timestamp.md#timestamptodate) | | Converts a Timestamp to a JavaScript Date object. This conversion causes a loss of precision since Date objects only support millisecond precision. | +| [toJSON()](./firestore_lite.timestamp.md#timestamptojson) | | Returns a JSON-serializable representation of this Timestamp. | +| [toMillis()](./firestore_lite.timestamp.md#timestamptomillis) | | Converts a Timestamp to a numeric timestamp (in milliseconds since epoch). This operation causes a loss of precision. | +| [toString()](./firestore_lite.timestamp.md#timestamptostring) | | Returns a textual representation of this Timestamp. | +| [valueOf()](./firestore_lite.timestamp.md#timestampvalueof) | | Converts this object to a primitive string, which allows Timestamp objects to be compared using the >, <=, >= and > operators. | + +## Timestamp.(constructor) + +Creates a new timestamp. + +Signature: + +```typescript +constructor( + seconds: number, + nanoseconds: number); +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| seconds | number | The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive. | +| nanoseconds | number | The non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanoseconds values that count forward in time. Must be from 0 to 999,999,999 inclusive. | + +## Timestamp.nanoseconds + +The fractions of a second at nanosecond resolution.\* + +Signature: + +```typescript +readonly nanoseconds: number; +``` + +## Timestamp.seconds + +The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. + +Signature: + +```typescript +readonly seconds: number; +``` + +## Timestamp.fromDate() + +Creates a new timestamp from the given date. + +Signature: + +```typescript +static fromDate(date: Date): Timestamp; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| date | Date | The date to initialize the Timestamp from. | + +Returns: + +[Timestamp](./firestore_lite.timestamp.md#timestamp_class) + +A new `Timestamp` representing the same point in time as the given date. + +## Timestamp.fromMillis() + +Creates a new timestamp from the given number of milliseconds. + +Signature: + +```typescript +static fromMillis(milliseconds: number): Timestamp; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| milliseconds | number | Number of milliseconds since Unix epoch 1970-01-01T00:00:00Z. | + +Returns: + +[Timestamp](./firestore_lite.timestamp.md#timestamp_class) + +A new `Timestamp` representing the same point in time as the given number of milliseconds. + +## Timestamp.isEqual() + +Returns true if this `Timestamp` is equal to the provided one. + +Signature: + +```typescript +isEqual(other: Timestamp): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| other | [Timestamp](./firestore_lite.timestamp.md#timestamp_class) | The Timestamp to compare against. | + +Returns: + +boolean + +true if this `Timestamp` is equal to the provided one. + +## Timestamp.now() + +Creates a new timestamp with the current date, with millisecond precision. + +Signature: + +```typescript +static now(): Timestamp; +``` +Returns: + +[Timestamp](./firestore_lite.timestamp.md#timestamp_class) + +a new timestamp representing the current date. + +## Timestamp.toDate() + +Converts a `Timestamp` to a JavaScript `Date` object. This conversion causes a loss of precision since `Date` objects only support millisecond precision. + +Signature: + +```typescript +toDate(): Date; +``` +Returns: + +Date + +JavaScript `Date` object representing the same point in time as this `Timestamp`, with millisecond precision. + +## Timestamp.toJSON() + +Returns a JSON-serializable representation of this `Timestamp`. + +Signature: + +```typescript +toJSON(): { + seconds: number; + nanoseconds: number; + }; +``` +Returns: + +{ seconds: number; nanoseconds: number; } + +## Timestamp.toMillis() + +Converts a `Timestamp` to a numeric timestamp (in milliseconds since epoch). This operation causes a loss of precision. + +Signature: + +```typescript +toMillis(): number; +``` +Returns: + +number + +The point in time corresponding to this timestamp, represented as the number of milliseconds since Unix epoch 1970-01-01T00:00:00Z. + +## Timestamp.toString() + +Returns a textual representation of this `Timestamp`. + +Signature: + +```typescript +toString(): string; +``` +Returns: + +string + +## Timestamp.valueOf() + +Converts this object to a primitive string, which allows `Timestamp` objects to be compared using the `>`, `<=`, `>=` and `>` operators. + +Signature: + +```typescript +valueOf(): string; +``` +Returns: + +string + diff --git a/docs-devsite/firestore_lite.transaction.md b/docs-devsite/firestore_lite.transaction.md new file mode 100644 index 00000000000..c643f08d66e --- /dev/null +++ b/docs-devsite/firestore_lite.transaction.md @@ -0,0 +1,190 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Transaction class +A reference to a transaction. + +The `Transaction` object passed to a transaction's `updateFunction` provides the methods to read and write data within the transaction context. See [runTransaction()](./firestore_.md#runtransaction). + +Signature: + +```typescript +export declare class Transaction +``` + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [delete(documentRef)](./firestore_lite.transaction.md#transactiondelete) | | Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). | +| [get(documentRef)](./firestore_lite.transaction.md#transactionget) | | Reads the document referenced by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). | +| [set(documentRef, data)](./firestore_lite.transaction.md#transactionset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. | +| [set(documentRef, data, options)](./firestore_lite.transaction.md#transactionset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document. | +| [update(documentRef, data)](./firestore_lite.transaction.md#transactionupdate) | | Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. | +| [update(documentRef, field, value, moreFieldsAndValues)](./firestore_lite.transaction.md#transactionupdate) | | Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist.Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects. | + +## Transaction.delete() + +Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). + +Signature: + +```typescript +delete(documentRef: DocumentReference): this; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to the document to be deleted. | + +Returns: + +this + +This `Transaction` instance. Used for chaining method calls. + +## Transaction.get() + +Reads the document referenced by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). + +Signature: + +```typescript +get(documentRef: DocumentReference): Promise>; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be read. | + +Returns: + +Promise<[DocumentSnapshot](./firestore_lite.documentsnapshot.md#documentsnapshot_class)<T>> + +A `DocumentSnapshot` with the read data. + +## Transaction.set() + +Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. + +Signature: + +```typescript +set(documentRef: DocumentReference, data: WithFieldValue): this; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | +| data | [WithFieldValue](./firestore_lite.md#withfieldvalue)<T> | An object of the fields and values for the document. | + +Returns: + +this + +This `Transaction` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not a valid Firestore document. + +## Transaction.set() + +Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. + +Signature: + +```typescript +set(documentRef: DocumentReference, data: PartialWithFieldValue, options: SetOptions): this; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | +| data | [PartialWithFieldValue](./firestore_lite.md#partialwithfieldvalue)<T> | An object of the fields and values for the document. | +| options | [SetOptions](./firestore_lite.md#setoptions) | An object to configure the set behavior. | + +Returns: + +this + +This `Transaction` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not a valid Firestore document. + +## Transaction.update() + +Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. + +Signature: + +```typescript +update(documentRef: DocumentReference, data: UpdateData): this; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be updated. | +| data | [UpdateData](./firestore_lite.md#updatedata)<T> | An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document. | + +Returns: + +this + +This `Transaction` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not valid Firestore data. + +## Transaction.update() + +Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. + +Nested fields can be updated by providing dot-separated field path strings or by providing `FieldPath` objects. + +Signature: + +```typescript +update(documentRef: DocumentReference, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): this; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to the document to be updated. | +| field | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The first field to update. | +| value | unknown | The first value. | +| moreFieldsAndValues | unknown\[\] | Additional key/value pairs. | + +Returns: + +this + +This `Transaction` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not valid Firestore data. + diff --git a/docs-devsite/firestore_lite.transactionoptions.md b/docs-devsite/firestore_lite.transactionoptions.md new file mode 100644 index 00000000000..94941df172a --- /dev/null +++ b/docs-devsite/firestore_lite.transactionoptions.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# TransactionOptions interface +Options to customize transaction behavior. + +Signature: + +```typescript +export declare interface TransactionOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [maxAttempts](./firestore_lite.transactionoptions.md#transactionoptionsmaxattempts) | number | Maximum number of attempts to commit, after which transaction fails. Default is 5. | + +## TransactionOptions.maxAttempts + +Maximum number of attempts to commit, after which transaction fails. Default is 5. + +Signature: + +```typescript +readonly maxAttempts?: number; +``` diff --git a/docs-devsite/firestore_lite.writebatch.md b/docs-devsite/firestore_lite.writebatch.md new file mode 100644 index 00000000000..141a99e8585 --- /dev/null +++ b/docs-devsite/firestore_lite.writebatch.md @@ -0,0 +1,181 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# WriteBatch class +A write batch, used to perform multiple writes as a single atomic unit. + +A `WriteBatch` object can be acquired by calling [writeBatch()](./firestore_.md#writebatch). It provides methods for adding writes to the write batch. None of the writes will be committed (or visible locally) until [WriteBatch.commit()](./firestore_.writebatch.md#writebatchcommit) is called. + +Signature: + +```typescript +export declare class WriteBatch +``` + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [commit()](./firestore_lite.writebatch.md#writebatchcommit) | | Commits all of the writes in this write batch as a single atomic unit.The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. | +| [delete(documentRef)](./firestore_lite.writebatch.md#writebatchdelete) | | Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). | +| [set(documentRef, data)](./firestore_lite.writebatch.md#writebatchset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. | +| [set(documentRef, data, options)](./firestore_lite.writebatch.md#writebatchset) | | Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document. | +| [update(documentRef, data)](./firestore_lite.writebatch.md#writebatchupdate) | | Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. | +| [update(documentRef, field, value, moreFieldsAndValues)](./firestore_lite.writebatch.md#writebatchupdate) | | Updates fields in the document referred to by this [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist.Nested fields can be update by providing dot-separated field path strings or by providing FieldPath objects. | + +## WriteBatch.commit() + +Commits all of the writes in this write batch as a single atomic unit. + +The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK. + +Signature: + +```typescript +commit(): Promise; +``` +Returns: + +Promise<void> + +A `Promise` resolved once all of the writes in the batch have been successfully written to the backend as an atomic unit (note that it won't resolve while you're offline). + +## WriteBatch.delete() + +Deletes the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). + +Signature: + +```typescript +delete(documentRef: DocumentReference): WriteBatch; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to the document to be deleted. | + +Returns: + +[WriteBatch](./firestore_lite.writebatch.md#writebatch_class) + +This `WriteBatch` instance. Used for chaining method calls. + +## WriteBatch.set() + +Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. + +Signature: + +```typescript +set(documentRef: DocumentReference, data: WithFieldValue): WriteBatch; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | +| data | [WithFieldValue](./firestore_lite.md#withfieldvalue)<T> | An object of the fields and values for the document. | + +Returns: + +[WriteBatch](./firestore_lite.writebatch.md#writebatch_class) + +This `WriteBatch` instance. Used for chaining method calls. + +## WriteBatch.set() + +Writes to the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). If the document does not exist yet, it will be created. If you provide `merge` or `mergeFields`, the provided data can be merged into an existing document. + +Signature: + +```typescript +set(documentRef: DocumentReference, data: PartialWithFieldValue, options: SetOptions): WriteBatch; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be set. | +| data | [PartialWithFieldValue](./firestore_lite.md#partialwithfieldvalue)<T> | An object of the fields and values for the document. | +| options | [SetOptions](./firestore_lite.md#setoptions) | An object to configure the set behavior. | + +Returns: + +[WriteBatch](./firestore_lite.writebatch.md#writebatch_class) + +This `WriteBatch` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not a valid Firestore document. + +## WriteBatch.update() + +Updates fields in the document referred to by the provided [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. + +Signature: + +```typescript +update(documentRef: DocumentReference, data: UpdateData): WriteBatch; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<T> | A reference to the document to be updated. | +| data | [UpdateData](./firestore_lite.md#updatedata)<T> | An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document. | + +Returns: + +[WriteBatch](./firestore_lite.writebatch.md#writebatch_class) + +This `WriteBatch` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not valid Firestore data. + +## WriteBatch.update() + +Updates fields in the document referred to by this [DocumentReference](./firestore_.documentreference.md#documentreference_class). The update will fail if applied to a document that does not exist. + +Nested fields can be update by providing dot-separated field path strings or by providing `FieldPath` objects. + +Signature: + +```typescript +update(documentRef: DocumentReference, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): WriteBatch; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| documentRef | [DocumentReference](./firestore_lite.documentreference.md#documentreference_class)<unknown> | A reference to the document to be updated. | +| field | string \| [FieldPath](./firestore_lite.fieldpath.md#fieldpath_class) | The first field to update. | +| value | unknown | The first value. | +| moreFieldsAndValues | unknown\[\] | Additional key value pairs. | + +Returns: + +[WriteBatch](./firestore_lite.writebatch.md#writebatch_class) + +This `WriteBatch` instance. Used for chaining method calls. + +## Exceptions + +Error - If the provided input is not valid Firestore data. + diff --git a/docs-devsite/functions.functions.md b/docs-devsite/functions.functions.md new file mode 100644 index 00000000000..da5e0585f45 --- /dev/null +++ b/docs-devsite/functions.functions.md @@ -0,0 +1,57 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Functions interface +A `Functions` instance. + +Signature: + +```typescript +export interface Functions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [app](./functions.functions.md#functionsapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this Functions instance is associated with. | +| [customDomain](./functions.functions.md#functionscustomdomain) | string \| null | A custom domain hosting the callable Cloud Functions. ex: https://mydomain.com | +| [region](./functions.functions.md#functionsregion) | string | The region the callable Cloud Functions are located in. Default is us-central-1. | + +## Functions.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `Functions` instance is associated with. + +Signature: + +```typescript +app: FirebaseApp; +``` + +## Functions.customDomain + +A custom domain hosting the callable Cloud Functions. ex: https://mydomain.com + +Signature: + +```typescript +customDomain: string | null; +``` + +## Functions.region + +The region the callable Cloud Functions are located in. Default is `us-central-1`. + +Signature: + +```typescript +region: string; +``` diff --git a/docs-devsite/functions.functionserror.md b/docs-devsite/functions.functionserror.md new file mode 100644 index 00000000000..3be96745b4c --- /dev/null +++ b/docs-devsite/functions.functionserror.md @@ -0,0 +1,47 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FunctionsError interface +An error returned by the Firebase Functions client SDK. + +Signature: + +```typescript +export interface FunctionsError extends FirebaseError +``` +Extends: [FirebaseError](./util.firebaseerror.md#firebaseerror_class) + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [code](./functions.functionserror.md#functionserrorcode) | [FunctionsErrorCode](./functions.md#functionserrorcode) | A standard error code that will be returned to the client. This also determines the HTTP status code of the response, as defined in code.proto. | +| [details](./functions.functionserror.md#functionserrordetails) | unknown | Extra data to be converted to JSON and included in the error response. | + +## FunctionsError.code + +A standard error code that will be returned to the client. This also determines the HTTP status code of the response, as defined in code.proto. + +Signature: + +```typescript +readonly code: FunctionsErrorCode; +``` + +## FunctionsError.details + +Extra data to be converted to JSON and included in the error response. + +Signature: + +```typescript +readonly details?: unknown; +``` diff --git a/docs-devsite/functions.httpscallableoptions.md b/docs-devsite/functions.httpscallableoptions.md new file mode 100644 index 00000000000..cb84abf2526 --- /dev/null +++ b/docs-devsite/functions.httpscallableoptions.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# HttpsCallableOptions interface +An interface for metadata about how calls should be executed. + +Signature: + +```typescript +export interface HttpsCallableOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [timeout](./functions.httpscallableoptions.md#httpscallableoptionstimeout) | number | Time in milliseconds after which to cancel if there is no response. Default is 70000. | + +## HttpsCallableOptions.timeout + +Time in milliseconds after which to cancel if there is no response. Default is 70000. + +Signature: + +```typescript +timeout?: number; +``` diff --git a/docs-devsite/functions.httpscallableresult.md b/docs-devsite/functions.httpscallableresult.md new file mode 100644 index 00000000000..6c9877f423b --- /dev/null +++ b/docs-devsite/functions.httpscallableresult.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# HttpsCallableResult interface +An `HttpsCallableResult` wraps a single result from a function call. + +Signature: + +```typescript +export interface HttpsCallableResult +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [data](./functions.httpscallableresult.md#httpscallableresultdata) | ResponseData | Data returned from callable function. | + +## HttpsCallableResult.data + +Data returned from callable function. + +Signature: + +```typescript +readonly data: ResponseData; +``` diff --git a/docs-devsite/functions.md b/docs-devsite/functions.md new file mode 100644 index 00000000000..35b5087e08e --- /dev/null +++ b/docs-devsite/functions.md @@ -0,0 +1,162 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# functions package +Cloud Functions for Firebase + +## Functions + +| Function | Description | +| --- | --- | +| function(app...) | +| [getFunctions(app, regionOrCustomDomain)](./functions.md#getfunctions) | Returns a [Functions](./functions.functions.md#functions_interface) instance for the given app. | +| function(functionsInstance...) | +| [connectFunctionsEmulator(functionsInstance, host, port)](./functions.md#connectfunctionsemulator) | Modify this instance to communicate with the Cloud Functions emulator.Note: this must be called before this instance has been used to do any operations. | +| [httpsCallable(functionsInstance, name, options)](./functions.md#httpscallable) | Returns a reference to the callable HTTPS trigger with the given name. | +| [httpsCallableFromURL(functionsInstance, url, options)](./functions.md#httpscallablefromurl) | Returns a reference to the callable HTTPS trigger with the specified url. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [Functions](./functions.functions.md#functions_interface) | A Functions instance. | +| [FunctionsError](./functions.functionserror.md#functionserror_interface) | An error returned by the Firebase Functions client SDK. | +| [HttpsCallableOptions](./functions.httpscallableoptions.md#httpscallableoptions_interface) | An interface for metadata about how calls should be executed. | +| [HttpsCallableResult](./functions.httpscallableresult.md#httpscallableresult_interface) | An HttpsCallableResult wraps a single result from a function call. | + +## Type Aliases + +| Type Alias | Description | +| --- | --- | +| [FunctionsErrorCode](./functions.md#functionserrorcode) | The set of Firebase Functions status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.mdPossible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (e.g. an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation. | +| [FunctionsErrorCodeCore](./functions.md#functionserrorcodecore) | Functions error code string appended after "functions/" product prefix. See [FunctionsErrorCode](./functions.md#functionserrorcode) for full documentation of codes. | +| [HttpsCallable](./functions.md#httpscallable) | A reference to a "callable" HTTP trigger in Google Cloud Functions. | + +## getFunctions() + +Returns a [Functions](./functions.functions.md#functions_interface) instance for the given app. + +Signature: + +```typescript +export declare function getFunctions(app?: FirebaseApp, regionOrCustomDomain?: string): Functions; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to use. | +| regionOrCustomDomain | string | one of: a) The region the callable functions are located in (ex: us-central1) b) A custom domain hosting the callable functions (ex: https://mydomain.com) | + +Returns: + +[Functions](./functions.functions.md#functions_interface) + +## connectFunctionsEmulator() + +Modify this instance to communicate with the Cloud Functions emulator. + +Note: this must be called before this instance has been used to do any operations. + +Signature: + +```typescript +export declare function connectFunctionsEmulator(functionsInstance: Functions, host: string, port: number): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| functionsInstance | [Functions](./functions.functions.md#functions_interface) | | +| host | string | The emulator host (ex: localhost) | +| port | number | The emulator port (ex: 5001) | + +Returns: + +void + +## httpsCallable() + +Returns a reference to the callable HTTPS trigger with the given name. + +Signature: + +```typescript +export declare function httpsCallable(functionsInstance: Functions, name: string, options?: HttpsCallableOptions): HttpsCallable; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| functionsInstance | [Functions](./functions.functions.md#functions_interface) | | +| name | string | The name of the trigger. | +| options | [HttpsCallableOptions](./functions.httpscallableoptions.md#httpscallableoptions_interface) | | + +Returns: + +[HttpsCallable](./functions.md#httpscallable)<RequestData, ResponseData> + +## httpsCallableFromURL() + +Returns a reference to the callable HTTPS trigger with the specified url. + +Signature: + +```typescript +export declare function httpsCallableFromURL(functionsInstance: Functions, url: string, options?: HttpsCallableOptions): HttpsCallable; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| functionsInstance | [Functions](./functions.functions.md#functions_interface) | | +| url | string | The url of the trigger. | +| options | [HttpsCallableOptions](./functions.httpscallableoptions.md#httpscallableoptions_interface) | | + +Returns: + +[HttpsCallable](./functions.md#httpscallable)<RequestData, ResponseData> + +## FunctionsErrorCode + +The set of Firebase Functions status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.md + +Possible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (e.g. an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation. + +Signature: + +```typescript +export declare type FunctionsErrorCode = `functions/${FunctionsErrorCodeCore}`; +``` + +## FunctionsErrorCodeCore + +Functions error code string appended after "functions/" product prefix. See [FunctionsErrorCode](./functions.md#functionserrorcode) for full documentation of codes. + +Signature: + +```typescript +export declare type FunctionsErrorCodeCore = 'ok' | 'cancelled' | 'unknown' | 'invalid-argument' | 'deadline-exceeded' | 'not-found' | 'already-exists' | 'permission-denied' | 'resource-exhausted' | 'failed-precondition' | 'aborted' | 'out-of-range' | 'unimplemented' | 'internal' | 'unavailable' | 'data-loss' | 'unauthenticated'; +``` + +## HttpsCallable + +A reference to a "callable" HTTP trigger in Google Cloud Functions. + +Signature: + +```typescript +export declare type HttpsCallable = (data?: RequestData | null) => Promise>; +``` diff --git a/docs-devsite/index.md b/docs-devsite/index.md new file mode 100644 index 00000000000..e19f70906ef --- /dev/null +++ b/docs-devsite/index.md @@ -0,0 +1,30 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# API Reference + +## Packages + +| Package | Description | +| --- | --- | +| [@firebase/analytics](./analytics.md#analytics_package) | Firebase Analytics | +| [@firebase/app](./app.md#app_package) | Firebase App | +| [@firebase/app-check](./app-check.md#app-check_package) | Firebase App Check | +| [@firebase/auth](./auth.md#auth_package) | Firebase Authentication | +| [@firebase/database](./database.md#database_package) | Firebase Realtime Database | +| [@firebase/firestore](./firestore.md#firestore_package) | Cloud Firestore | +| [@firebase/functions](./functions.md#functions_package) | Cloud Functions for Firebase | +| [@firebase/installations](./installations.md#installations_package) | Firebase Installations | +| [@firebase/messaging](./messaging.md#messaging_package) | Firebase Cloud Messaging | +| [@firebase/performance](./performance.md#performance_package) | Firebase Performance Monitoring | +| [@firebase/remote-config](./remote-config.md#remote-config_package) | Firebase Remote Config | +| [@firebase/storage](./storage.md#storage_package) | Cloud Storage for Firebase | + diff --git a/docs-devsite/installations.installations.md b/docs-devsite/installations.installations.md new file mode 100644 index 00000000000..4c1107e0354 --- /dev/null +++ b/docs-devsite/installations.installations.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Installations interface +Public interface of the Firebase Installations SDK. + +Signature: + +```typescript +export interface Installations +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [app](./installations.installations.md#installationsapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this Installations instance is associated with. | + +## Installations.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `Installations` instance is associated with. + +Signature: + +```typescript +app: FirebaseApp; +``` diff --git a/docs-devsite/installations.md b/docs-devsite/installations.md new file mode 100644 index 00000000000..1ef8b80b00e --- /dev/null +++ b/docs-devsite/installations.md @@ -0,0 +1,162 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# installations package +Firebase Installations + +## Functions + +| Function | Description | +| --- | --- | +| function(app...) | +| [getInstallations(app)](./installations.md#getinstallations) | Returns an instance of [Installations](./installations.installations.md#installations_interface) associated with the given [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. | +| function(installations...) | +| [deleteInstallations(installations)](./installations.md#deleteinstallations) | Deletes the Firebase Installation and all associated data. | +| [getId(installations)](./installations.md#getid) | Creates a Firebase Installation if there isn't one for the app and returns the Installation ID. | +| [getToken(installations, forceRefresh)](./installations.md#gettoken) | Returns a Firebase Installations auth token, identifying the current Firebase Installation. | +| [onIdChange(installations, callback)](./installations.md#onidchange) | Sets a new callback that will get called when Installation ID changes. Returns an unsubscribe function that will remove the callback when called. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [Installations](./installations.installations.md#installations_interface) | Public interface of the Firebase Installations SDK. | + +## Type Aliases + +| Type Alias | Description | +| --- | --- | +| [IdChangeCallbackFn](./installations.md#idchangecallbackfn) | An user defined callback function that gets called when Installations ID changes. | +| [IdChangeUnsubscribeFn](./installations.md#idchangeunsubscribefn) | Unsubscribe a callback function previously added via [IdChangeCallbackFn](./installations.md#idchangecallbackfn). | + +## getInstallations() + +Returns an instance of [Installations](./installations.installations.md#installations_interface) associated with the given [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. + +Signature: + +```typescript +export declare function getInstallations(app?: FirebaseApp): Installations; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. | + +Returns: + +[Installations](./installations.installations.md#installations_interface) + +## deleteInstallations() + +Deletes the Firebase Installation and all associated data. + +Signature: + +```typescript +export declare function deleteInstallations(installations: Installations): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| installations | [Installations](./installations.installations.md#installations_interface) | The Installations instance. | + +Returns: + +Promise<void> + +## getId() + +Creates a Firebase Installation if there isn't one for the app and returns the Installation ID. + +Signature: + +```typescript +export declare function getId(installations: Installations): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| installations | [Installations](./installations.installations.md#installations_interface) | The Installations instance. | + +Returns: + +Promise<string> + +## getToken() + +Returns a Firebase Installations auth token, identifying the current Firebase Installation. + +Signature: + +```typescript +export declare function getToken(installations: Installations, forceRefresh?: boolean): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| installations | [Installations](./installations.installations.md#installations_interface) | The Installations instance. | +| forceRefresh | boolean | Force refresh regardless of token expiration. | + +Returns: + +Promise<string> + +## onIdChange() + +Sets a new callback that will get called when Installation ID changes. Returns an unsubscribe function that will remove the callback when called. + +Signature: + +```typescript +export declare function onIdChange(installations: Installations, callback: IdChangeCallbackFn): IdChangeUnsubscribeFn; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| installations | [Installations](./installations.installations.md#installations_interface) | The Installations instance. | +| callback | [IdChangeCallbackFn](./installations.md#idchangecallbackfn) | The callback function that is invoked when FID changes. | + +Returns: + +[IdChangeUnsubscribeFn](./installations.md#idchangeunsubscribefn) + +A function that can be called to unsubscribe. + +## IdChangeCallbackFn + +An user defined callback function that gets called when Installations ID changes. + +Signature: + +```typescript +export declare type IdChangeCallbackFn = (installationId: string) => void; +``` + +## IdChangeUnsubscribeFn + +Unsubscribe a callback function previously added via [IdChangeCallbackFn](./installations.md#idchangecallbackfn). + +Signature: + +```typescript +export declare type IdChangeUnsubscribeFn = () => void; +``` diff --git a/docs-devsite/messaging.md b/docs-devsite/messaging.md new file mode 100644 index 00000000000..ffbdd9ee3d8 --- /dev/null +++ b/docs-devsite/messaging.md @@ -0,0 +1,19 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# messaging package +Firebase Cloud Messaging + +| Entry Point | Description | +| --- | --- | +| [/](./messaging_.md#@firebase/messaging) | | +| [/sw](./messaging_sw.md#@firebase/messaging/sw) | | + diff --git a/docs-devsite/messaging_.fcmoptions.md b/docs-devsite/messaging_.fcmoptions.md new file mode 100644 index 00000000000..15f6123bae2 --- /dev/null +++ b/docs-devsite/messaging_.fcmoptions.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FcmOptions interface +Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) + +Signature: + +```typescript +export interface FcmOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [analyticsLabel](./messaging_.fcmoptions.md#fcmoptionsanalyticslabel) | string | The label associated with the message's analytics data. | +| [link](./messaging_.fcmoptions.md#fcmoptionslink) | string | The link to open when the user clicks on the notification. | + +## FcmOptions.analyticsLabel + +The label associated with the message's analytics data. + +Signature: + +```typescript +analyticsLabel?: string; +``` + +## FcmOptions.link + +The link to open when the user clicks on the notification. + +Signature: + +```typescript +link?: string; +``` diff --git a/docs-devsite/messaging_.gettokenoptions.md b/docs-devsite/messaging_.gettokenoptions.md new file mode 100644 index 00000000000..ed506fb5666 --- /dev/null +++ b/docs-devsite/messaging_.gettokenoptions.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# GetTokenOptions interface +Options for [getToken()](./messaging_.md#gettoken) + +Signature: + +```typescript +export interface GetTokenOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [serviceWorkerRegistration](./messaging_.gettokenoptions.md#gettokenoptionsserviceworkerregistration) | ServiceWorkerRegistration | The service worker registration for receiving push messaging. If the registration is not provided explicitly, you need to have a firebase-messaging-sw.js at your root location. See [Retrieve the current registration token](https://firebase.google.com/docs/cloud-messaging/js/client#retrieve-the-current-registration-token) for more details. | +| [vapidKey](./messaging_.gettokenoptions.md#gettokenoptionsvapidkey) | string | The public server key provided to push services. It is used to authenticate the push subscribers to receive push messages only from sending servers that hold the corresponding private key. If it is not provided, a default VAPID key is used. Note that some push services (Chrome Push Service) require a non-default VAPID key. Therefore, it is recommended to generate and import a VAPID key for your project with [Configure Web Credentials with FCM](https://firebase.google.com/docs/cloud-messaging/js/client#configure_web_credentials_with_fcm). See [The Web Push Protocol](https://developers.google.com/web/fundamentals/push-notifications/web-push-protocol) for details on web push services. | + +## GetTokenOptions.serviceWorkerRegistration + +The service worker registration for receiving push messaging. If the registration is not provided explicitly, you need to have a `firebase-messaging-sw.js` at your root location. See [Retrieve the current registration token](https://firebase.google.com/docs/cloud-messaging/js/client#retrieve-the-current-registration-token) for more details. + +Signature: + +```typescript +serviceWorkerRegistration?: ServiceWorkerRegistration; +``` + +## GetTokenOptions.vapidKey + +The public server key provided to push services. It is used to authenticate the push subscribers to receive push messages only from sending servers that hold the corresponding private key. If it is not provided, a default VAPID key is used. Note that some push services (Chrome Push Service) require a non-default VAPID key. Therefore, it is recommended to generate and import a VAPID key for your project with [Configure Web Credentials with FCM](https://firebase.google.com/docs/cloud-messaging/js/client#configure_web_credentials_with_fcm). See [The Web Push Protocol](https://developers.google.com/web/fundamentals/push-notifications/web-push-protocol) for details on web push services. + +Signature: + +```typescript +vapidKey?: string; +``` diff --git a/docs-devsite/messaging_.md b/docs-devsite/messaging_.md new file mode 100644 index 00000000000..ad04429ac94 --- /dev/null +++ b/docs-devsite/messaging_.md @@ -0,0 +1,143 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# @firebase/messaging + +## Functions + +| Function | Description | +| --- | --- | +| function(app...) | +| [getMessaging(app)](./messaging_.md#getmessaging) | Retrieves a Firebase Cloud Messaging instance. | +| function(messaging...) | +| [deleteToken(messaging)](./messaging_.md#deletetoken) | Deletes the registration token associated with this [Messaging](./messaging_.messaging.md#messaging_interface) instance and unsubscribes the [Messaging](./messaging_.messaging.md#messaging_interface) instance from the push subscription. | +| [getToken(messaging, options)](./messaging_.md#gettoken) | Subscribes the [Messaging](./messaging_.messaging.md#messaging_interface) instance to push notifications. Returns an Firebase Cloud Messaging registration token that can be used to send push messages to that [Messaging](./messaging_.messaging.md#messaging_interface) instance.If a notification permission isn't already granted, this method asks the user for permission. The returned promise rejects if the user does not allow the app to show notifications. | +| [onMessage(messaging, nextOrObserver)](./messaging_.md#onmessage) | When a push message is received and the user is currently on a page for your origin, the message is passed to the page and an onMessage() event is dispatched with the payload of the push message. | +| function() | +| [isSupported()](./messaging_.md#issupported) | Checks if all required APIs exist in the browser. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [FcmOptions](./messaging_.fcmoptions.md#fcmoptions_interface) | Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) | +| [GetTokenOptions](./messaging_.gettokenoptions.md#gettokenoptions_interface) | Options for [getToken()](./messaging_.md#gettoken) | +| [MessagePayload](./messaging_.messagepayload.md#messagepayload_interface) | Message payload that contains the notification payload that is represented with [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) and the data payload that contains an arbitrary number of key-value pairs sent by developers through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) | +| [Messaging](./messaging_.messaging.md#messaging_interface) | Public interface of the Firebase Cloud Messaging SDK. | +| [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) | Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) | + +## getMessaging() + +Retrieves a Firebase Cloud Messaging instance. + +Signature: + +```typescript +export declare function getMessagingInWindow(app?: FirebaseApp): Messaging; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | | + +Returns: + +[Messaging](./messaging_.messaging.md#messaging_interface) + +The Firebase Cloud Messaging instance associated with the provided firebase app. + +## deleteToken() + +Deletes the registration token associated with this [Messaging](./messaging_.messaging.md#messaging_interface) instance and unsubscribes the [Messaging](./messaging_.messaging.md#messaging_interface) instance from the push subscription. + +Signature: + +```typescript +export declare function deleteToken(messaging: Messaging): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| messaging | [Messaging](./messaging_.messaging.md#messaging_interface) | The [Messaging](./messaging_.messaging.md#messaging_interface) instance. | + +Returns: + +Promise<boolean> + +The promise resolves when the token has been successfully deleted. + +## getToken() + +Subscribes the [Messaging](./messaging_.messaging.md#messaging_interface) instance to push notifications. Returns an Firebase Cloud Messaging registration token that can be used to send push messages to that [Messaging](./messaging_.messaging.md#messaging_interface) instance. + +If a notification permission isn't already granted, this method asks the user for permission. The returned promise rejects if the user does not allow the app to show notifications. + +Signature: + +```typescript +export declare function getToken(messaging: Messaging, options?: GetTokenOptions): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| messaging | [Messaging](./messaging_.messaging.md#messaging_interface) | The [Messaging](./messaging_.messaging.md#messaging_interface) instance. | +| options | [GetTokenOptions](./messaging_.gettokenoptions.md#gettokenoptions_interface) | Provides an optional vapid key and an optinoal service worker registration | + +Returns: + +Promise<string> + +The promise resolves with an FCM registration token. + +## onMessage() + +When a push message is received and the user is currently on a page for your origin, the message is passed to the page and an `onMessage()` event is dispatched with the payload of the push message. + +Signature: + +```typescript +export declare function onMessage(messaging: Messaging, nextOrObserver: NextFn | Observer): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| messaging | [Messaging](./messaging_.messaging.md#messaging_interface) | The [Messaging](./messaging_.messaging.md#messaging_interface) instance. | +| nextOrObserver | [NextFn](./util.md#nextfn)<[MessagePayload](./messaging_.messagepayload.md#messagepayload_interface)> \| [Observer](./util.observer.md#observer_interface)<[MessagePayload](./messaging_.messagepayload.md#messagepayload_interface)> | This function, or observer object with next defined, is called when a message is received and the user is currently viewing your page. | + +Returns: + +[Unsubscribe](./util.md#unsubscribe) + +To stop listening for messages execute this returned function. + +## isSupported() + +Checks if all required APIs exist in the browser. + +Signature: + +```typescript +export declare function isWindowSupported(): Promise; +``` +Returns: + +Promise<boolean> + +a Promise that resolves to a boolean. + diff --git a/docs-devsite/messaging_.messagepayload.md b/docs-devsite/messaging_.messagepayload.md new file mode 100644 index 00000000000..1a944ebbc52 --- /dev/null +++ b/docs-devsite/messaging_.messagepayload.md @@ -0,0 +1,92 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# MessagePayload interface +Message payload that contains the notification payload that is represented with [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) and the data payload that contains an arbitrary number of key-value pairs sent by developers through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) + +Signature: + +```typescript +export interface MessagePayload +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [collapseKey](./messaging_.messagepayload.md#messagepayloadcollapsekey) | string | The collapse key of the message. See [Non-collapsible and collapsible messages](https://firebase.google.com/docs/cloud-messaging/concept-options#collapsible_and_non-collapsible_messages) | +| [data](./messaging_.messagepayload.md#messagepayloaddata) | { \[key: string\]: string; } | Arbitrary key/value payload. | +| [fcmOptions](./messaging_.messagepayload.md#messagepayloadfcmoptions) | [FcmOptions](./messaging_.fcmoptions.md#fcmoptions_interface) | Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) | +| [from](./messaging_.messagepayload.md#messagepayloadfrom) | string | The sender of this message. | +| [messageId](./messaging_.messagepayload.md#messagepayloadmessageid) | string | The message id of a message. | +| [notification](./messaging_.messagepayload.md#messagepayloadnotification) | [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) | Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) | + +## MessagePayload.collapseKey + +The collapse key of the message. See [Non-collapsible and collapsible messages](https://firebase.google.com/docs/cloud-messaging/concept-options#collapsible_and_non-collapsible_messages) + +Signature: + +```typescript +collapseKey: string; +``` + +## MessagePayload.data + +Arbitrary key/value payload. + +Signature: + +```typescript +data?: { + [key: string]: string; + }; +``` + +## MessagePayload.fcmOptions + +Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) + +Signature: + +```typescript +fcmOptions?: FcmOptions; +``` + +## MessagePayload.from + +The sender of this message. + +Signature: + +```typescript +from: string; +``` + +## MessagePayload.messageId + +The message id of a message. + +Signature: + +```typescript +messageId: string; +``` + +## MessagePayload.notification + +Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) + +Signature: + +```typescript +notification?: NotificationPayload; +``` diff --git a/docs-devsite/messaging_.messaging.md b/docs-devsite/messaging_.messaging.md new file mode 100644 index 00000000000..8d16b75467a --- /dev/null +++ b/docs-devsite/messaging_.messaging.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Messaging interface +Public interface of the Firebase Cloud Messaging SDK. + +Signature: + +```typescript +export interface Messaging +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [app](./messaging_.messaging.md#messagingapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this Messaging instance is associated with. | + +## Messaging.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `Messaging` instance is associated with. + +Signature: + +```typescript +app: FirebaseApp; +``` diff --git a/docs-devsite/messaging_.notificationpayload.md b/docs-devsite/messaging_.notificationpayload.md new file mode 100644 index 00000000000..5978a55b6bf --- /dev/null +++ b/docs-devsite/messaging_.notificationpayload.md @@ -0,0 +1,68 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# NotificationPayload interface +Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) + +Signature: + +```typescript +export interface NotificationPayload +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [body](./messaging_.notificationpayload.md#notificationpayloadbody) | string | The notification's body text. | +| [icon](./messaging_.notificationpayload.md#notificationpayloadicon) | string | The URL to use for the notification's icon. If you don't send this key in the request, FCM displays the launcher icon specified in your app manifest. | +| [image](./messaging_.notificationpayload.md#notificationpayloadimage) | string | The URL of an image that is downloaded on the device and displayed in the notification. | +| [title](./messaging_.notificationpayload.md#notificationpayloadtitle) | string | The notification's title. | + +## NotificationPayload.body + +The notification's body text. + +Signature: + +```typescript +body?: string; +``` + +## NotificationPayload.icon + +The URL to use for the notification's icon. If you don't send this key in the request, FCM displays the launcher icon specified in your app manifest. + +Signature: + +```typescript +icon?: string; +``` + +## NotificationPayload.image + +The URL of an image that is downloaded on the device and displayed in the notification. + +Signature: + +```typescript +image?: string; +``` + +## NotificationPayload.title + +The notification's title. + +Signature: + +```typescript +title?: string; +``` diff --git a/docs-devsite/messaging_sw.fcmoptions.md b/docs-devsite/messaging_sw.fcmoptions.md new file mode 100644 index 00000000000..55fdddaa0e3 --- /dev/null +++ b/docs-devsite/messaging_sw.fcmoptions.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FcmOptions interface +Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) + +Signature: + +```typescript +export interface FcmOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [analyticsLabel](./messaging_sw.fcmoptions.md#fcmoptionsanalyticslabel) | string | The label associated with the message's analytics data. | +| [link](./messaging_sw.fcmoptions.md#fcmoptionslink) | string | The link to open when the user clicks on the notification. | + +## FcmOptions.analyticsLabel + +The label associated with the message's analytics data. + +Signature: + +```typescript +analyticsLabel?: string; +``` + +## FcmOptions.link + +The link to open when the user clicks on the notification. + +Signature: + +```typescript +link?: string; +``` diff --git a/docs-devsite/messaging_sw.gettokenoptions.md b/docs-devsite/messaging_sw.gettokenoptions.md new file mode 100644 index 00000000000..5e724513a02 --- /dev/null +++ b/docs-devsite/messaging_sw.gettokenoptions.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# GetTokenOptions interface +Options for [getToken()](./messaging_.md#gettoken) + +Signature: + +```typescript +export interface GetTokenOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [serviceWorkerRegistration](./messaging_sw.gettokenoptions.md#gettokenoptionsserviceworkerregistration) | ServiceWorkerRegistration | The service worker registration for receiving push messaging. If the registration is not provided explicitly, you need to have a firebase-messaging-sw.js at your root location. See [Retrieve the current registration token](https://firebase.google.com/docs/cloud-messaging/js/client#retrieve-the-current-registration-token) for more details. | +| [vapidKey](./messaging_sw.gettokenoptions.md#gettokenoptionsvapidkey) | string | The public server key provided to push services. It is used to authenticate the push subscribers to receive push messages only from sending servers that hold the corresponding private key. If it is not provided, a default VAPID key is used. Note that some push services (Chrome Push Service) require a non-default VAPID key. Therefore, it is recommended to generate and import a VAPID key for your project with [Configure Web Credentials with FCM](https://firebase.google.com/docs/cloud-messaging/js/client#configure_web_credentials_with_fcm). See [The Web Push Protocol](https://developers.google.com/web/fundamentals/push-notifications/web-push-protocol) for details on web push services. | + +## GetTokenOptions.serviceWorkerRegistration + +The service worker registration for receiving push messaging. If the registration is not provided explicitly, you need to have a `firebase-messaging-sw.js` at your root location. See [Retrieve the current registration token](https://firebase.google.com/docs/cloud-messaging/js/client#retrieve-the-current-registration-token) for more details. + +Signature: + +```typescript +serviceWorkerRegistration?: ServiceWorkerRegistration; +``` + +## GetTokenOptions.vapidKey + +The public server key provided to push services. It is used to authenticate the push subscribers to receive push messages only from sending servers that hold the corresponding private key. If it is not provided, a default VAPID key is used. Note that some push services (Chrome Push Service) require a non-default VAPID key. Therefore, it is recommended to generate and import a VAPID key for your project with [Configure Web Credentials with FCM](https://firebase.google.com/docs/cloud-messaging/js/client#configure_web_credentials_with_fcm). See [The Web Push Protocol](https://developers.google.com/web/fundamentals/push-notifications/web-push-protocol) for details on web push services. + +Signature: + +```typescript +vapidKey?: string; +``` diff --git a/docs-devsite/messaging_sw.md b/docs-devsite/messaging_sw.md new file mode 100644 index 00000000000..0950fc61034 --- /dev/null +++ b/docs-devsite/messaging_sw.md @@ -0,0 +1,116 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# @firebase/messaging/sw + +## Functions + +| Function | Description | +| --- | --- | +| function(app...) | +| [getMessaging(app)](./messaging_sw.md#getmessaging) | Retrieves a Firebase Cloud Messaging instance. | +| function(messaging...) | +| [experimentalSetDeliveryMetricsExportedToBigQueryEnabled(messaging, enable)](./messaging_sw.md#experimentalsetdeliverymetricsexportedtobigqueryenabled) | Enables or disables Firebase Cloud Messaging message delivery metrics export to BigQuery. By default, message delivery metrics are not exported to BigQuery. Use this method to enable or disable the export at runtime. | +| [onBackgroundMessage(messaging, nextOrObserver)](./messaging_sw.md#onbackgroundmessage) | Called when a message is received while the app is in the background. An app is considered to be in the background if no active window is displayed. | +| function() | +| [isSupported()](./messaging_sw.md#issupported) | Checks whether all required APIs exist within SW Context | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [FcmOptions](./messaging_sw.fcmoptions.md#fcmoptions_interface) | Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) | +| [GetTokenOptions](./messaging_sw.gettokenoptions.md#gettokenoptions_interface) | Options for [getToken()](./messaging_.md#gettoken) | +| [MessagePayload](./messaging_sw.messagepayload.md#messagepayload_interface) | Message payload that contains the notification payload that is represented with [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) and the data payload that contains an arbitrary number of key-value pairs sent by developers through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) | +| [Messaging](./messaging_sw.messaging.md#messaging_interface) | Public interface of the Firebase Cloud Messaging SDK. | +| [NotificationPayload](./messaging_sw.notificationpayload.md#notificationpayload_interface) | Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) | + +## getMessaging() + +Retrieves a Firebase Cloud Messaging instance. + +Signature: + +```typescript +export declare function getMessagingInSw(app?: FirebaseApp): Messaging; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | | + +Returns: + +[Messaging](./messaging_.messaging.md#messaging_interface) + +The Firebase Cloud Messaging instance associated with the provided firebase app. + +## experimentalSetDeliveryMetricsExportedToBigQueryEnabled() + +Enables or disables Firebase Cloud Messaging message delivery metrics export to BigQuery. By default, message delivery metrics are not exported to BigQuery. Use this method to enable or disable the export at runtime. + +Signature: + +```typescript +export declare function experimentalSetDeliveryMetricsExportedToBigQueryEnabled(messaging: Messaging, enable: boolean): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| messaging | [Messaging](./messaging_.messaging.md#messaging_interface) | The FirebaseMessaging instance. | +| enable | boolean | Whether Firebase Cloud Messaging should export message delivery metrics to BigQuery. | + +Returns: + +void + +## onBackgroundMessage() + +Called when a message is received while the app is in the background. An app is considered to be in the background if no active window is displayed. + +Signature: + +```typescript +export declare function onBackgroundMessage(messaging: Messaging, nextOrObserver: NextFn | Observer): Unsubscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| messaging | [Messaging](./messaging_.messaging.md#messaging_interface) | The [Messaging](./messaging_.messaging.md#messaging_interface) instance. | +| nextOrObserver | [NextFn](./util.md#nextfn)<[MessagePayload](./messaging_.messagepayload.md#messagepayload_interface)> \| [Observer](./util.observer.md#observer_interface)<[MessagePayload](./messaging_.messagepayload.md#messagepayload_interface)> | This function, or observer object with next defined, is called when a message is received and the app is currently in the background. | + +Returns: + +[Unsubscribe](./util.md#unsubscribe) + +To stop listening for messages execute this returned function + +## isSupported() + +Checks whether all required APIs exist within SW Context + +Signature: + +```typescript +export declare function isSwSupported(): Promise; +``` +Returns: + +Promise<boolean> + +a Promise that resolves to a boolean. + diff --git a/docs-devsite/messaging_sw.messagepayload.md b/docs-devsite/messaging_sw.messagepayload.md new file mode 100644 index 00000000000..2037bb0016d --- /dev/null +++ b/docs-devsite/messaging_sw.messagepayload.md @@ -0,0 +1,92 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# MessagePayload interface +Message payload that contains the notification payload that is represented with [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) and the data payload that contains an arbitrary number of key-value pairs sent by developers through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) + +Signature: + +```typescript +export interface MessagePayload +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [collapseKey](./messaging_sw.messagepayload.md#messagepayloadcollapsekey) | string | The collapse key of the message. See [Non-collapsible and collapsible messages](https://firebase.google.com/docs/cloud-messaging/concept-options#collapsible_and_non-collapsible_messages) | +| [data](./messaging_sw.messagepayload.md#messagepayloaddata) | { \[key: string\]: string; } | Arbitrary key/value payload. | +| [fcmOptions](./messaging_sw.messagepayload.md#messagepayloadfcmoptions) | [FcmOptions](./messaging_.fcmoptions.md#fcmoptions_interface) | Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) | +| [from](./messaging_sw.messagepayload.md#messagepayloadfrom) | string | The sender of this message. | +| [messageId](./messaging_sw.messagepayload.md#messagepayloadmessageid) | string | The message id of a message. | +| [notification](./messaging_sw.messagepayload.md#messagepayloadnotification) | [NotificationPayload](./messaging_.notificationpayload.md#notificationpayload_interface) | Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) | + +## MessagePayload.collapseKey + +The collapse key of the message. See [Non-collapsible and collapsible messages](https://firebase.google.com/docs/cloud-messaging/concept-options#collapsible_and_non-collapsible_messages) + +Signature: + +```typescript +collapseKey: string; +``` + +## MessagePayload.data + +Arbitrary key/value payload. + +Signature: + +```typescript +data?: { + [key: string]: string; + }; +``` + +## MessagePayload.fcmOptions + +Options for features provided by the FCM SDK for Web. See [WebpushFcmOptions](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions) + +Signature: + +```typescript +fcmOptions?: FcmOptions; +``` + +## MessagePayload.from + +The sender of this message. + +Signature: + +```typescript +from: string; +``` + +## MessagePayload.messageId + +The message id of a message. + +Signature: + +```typescript +messageId: string; +``` + +## MessagePayload.notification + +Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) + +Signature: + +```typescript +notification?: NotificationPayload; +``` diff --git a/docs-devsite/messaging_sw.messaging.md b/docs-devsite/messaging_sw.messaging.md new file mode 100644 index 00000000000..cfd15fe9aaf --- /dev/null +++ b/docs-devsite/messaging_sw.messaging.md @@ -0,0 +1,35 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Messaging interface +Public interface of the Firebase Cloud Messaging SDK. + +Signature: + +```typescript +export interface Messaging +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [app](./messaging_sw.messaging.md#messagingapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this Messaging instance is associated with. | + +## Messaging.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `Messaging` instance is associated with. + +Signature: + +```typescript +app: FirebaseApp; +``` diff --git a/docs-devsite/messaging_sw.notificationpayload.md b/docs-devsite/messaging_sw.notificationpayload.md new file mode 100644 index 00000000000..c49ecfdf123 --- /dev/null +++ b/docs-devsite/messaging_sw.notificationpayload.md @@ -0,0 +1,68 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# NotificationPayload interface +Display notification details. They are sent through the [Send API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification) + +Signature: + +```typescript +export interface NotificationPayload +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [body](./messaging_sw.notificationpayload.md#notificationpayloadbody) | string | The notification's body text. | +| [icon](./messaging_sw.notificationpayload.md#notificationpayloadicon) | string | The URL to use for the notification's icon. If you don't send this key in the request, FCM displays the launcher icon specified in your app manifest. | +| [image](./messaging_sw.notificationpayload.md#notificationpayloadimage) | string | The URL of an image that is downloaded on the device and displayed in the notification. | +| [title](./messaging_sw.notificationpayload.md#notificationpayloadtitle) | string | The notification's title. | + +## NotificationPayload.body + +The notification's body text. + +Signature: + +```typescript +body?: string; +``` + +## NotificationPayload.icon + +The URL to use for the notification's icon. If you don't send this key in the request, FCM displays the launcher icon specified in your app manifest. + +Signature: + +```typescript +icon?: string; +``` + +## NotificationPayload.image + +The URL of an image that is downloaded on the device and displayed in the notification. + +Signature: + +```typescript +image?: string; +``` + +## NotificationPayload.title + +The notification's title. + +Signature: + +```typescript +title?: string; +``` diff --git a/docs-devsite/performance.firebaseperformance.md b/docs-devsite/performance.firebaseperformance.md new file mode 100644 index 00000000000..d8aea429952 --- /dev/null +++ b/docs-devsite/performance.firebaseperformance.md @@ -0,0 +1,57 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FirebasePerformance interface +The Firebase Performance Monitoring service interface. + +Signature: + +```typescript +export interface FirebasePerformance +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [app](./performance.firebaseperformance.md#firebaseperformanceapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this FirebasePerformance instance is associated with. | +| [dataCollectionEnabled](./performance.firebaseperformance.md#firebaseperformancedatacollectionenabled) | boolean | Controls the logging of custom traces. | +| [instrumentationEnabled](./performance.firebaseperformance.md#firebaseperformanceinstrumentationenabled) | boolean | Controls the logging of automatic traces and HTTP/S network monitoring. | + +## FirebasePerformance.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `FirebasePerformance` instance is associated with. + +Signature: + +```typescript +app: FirebaseApp; +``` + +## FirebasePerformance.dataCollectionEnabled + +Controls the logging of custom traces. + +Signature: + +```typescript +dataCollectionEnabled: boolean; +``` + +## FirebasePerformance.instrumentationEnabled + +Controls the logging of automatic traces and HTTP/S network monitoring. + +Signature: + +```typescript +instrumentationEnabled: boolean; +``` diff --git a/docs-devsite/performance.md b/docs-devsite/performance.md new file mode 100644 index 00000000000..247002ed70a --- /dev/null +++ b/docs-devsite/performance.md @@ -0,0 +1,94 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# performance package +Firebase Performance Monitoring + +## Functions + +| Function | Description | +| --- | --- | +| function(app...) | +| [getPerformance(app)](./performance.md#getperformance) | Returns a [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) instance for the given app. | +| [initializePerformance(app, settings)](./performance.md#initializeperformance) | Returns a [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) instance for the given app. Can only be called once. | +| function(performance...) | +| [trace(performance, name)](./performance.md#trace) | Returns a new PerformanceTrace instance. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) | The Firebase Performance Monitoring service interface. | +| [PerformanceSettings](./performance.performancesettings.md#performancesettings_interface) | Defines configuration options for the Performance Monitoring SDK. | +| [PerformanceTrace](./performance.performancetrace.md#performancetrace_interface) | The interface representing a Trace. | + +## getPerformance() + +Returns a [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) instance for the given app. + +Signature: + +```typescript +export declare function getPerformance(app?: FirebaseApp): FirebasePerformance; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to use. | + +Returns: + +[FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) + +## initializePerformance() + +Returns a [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) instance for the given app. Can only be called once. + +Signature: + +```typescript +export declare function initializePerformance(app: FirebaseApp, settings?: PerformanceSettings): FirebasePerformance; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) to use. | +| settings | [PerformanceSettings](./performance.performancesettings.md#performancesettings_interface) | Optional settings for the [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) instance. | + +Returns: + +[FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) + +## trace() + +Returns a new `PerformanceTrace` instance. + +Signature: + +```typescript +export declare function trace(performance: FirebasePerformance, name: string): PerformanceTrace; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| performance | [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) | The [FirebasePerformance](./performance.firebaseperformance.md#firebaseperformance_interface) instance to use. | +| name | string | The name of the trace. | + +Returns: + +[PerformanceTrace](./performance.performancetrace.md#performancetrace_interface) + diff --git a/docs-devsite/performance.performancesettings.md b/docs-devsite/performance.performancesettings.md new file mode 100644 index 00000000000..9d85a96ce6a --- /dev/null +++ b/docs-devsite/performance.performancesettings.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# PerformanceSettings interface +Defines configuration options for the Performance Monitoring SDK. + +Signature: + +```typescript +export interface PerformanceSettings +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [dataCollectionEnabled](./performance.performancesettings.md#performancesettingsdatacollectionenabled) | boolean | Whether to collect custom events. | +| [instrumentationEnabled](./performance.performancesettings.md#performancesettingsinstrumentationenabled) | boolean | Whether to collect out of the box events. | + +## PerformanceSettings.dataCollectionEnabled + +Whether to collect custom events. + +Signature: + +```typescript +dataCollectionEnabled?: boolean; +``` + +## PerformanceSettings.instrumentationEnabled + +Whether to collect out of the box events. + +Signature: + +```typescript +instrumentationEnabled?: boolean; +``` diff --git a/docs-devsite/performance.performancetrace.md b/docs-devsite/performance.performancetrace.md new file mode 100644 index 00000000000..ffda20476da --- /dev/null +++ b/docs-devsite/performance.performancetrace.md @@ -0,0 +1,228 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# PerformanceTrace interface +The interface representing a `Trace`. + +Signature: + +```typescript +export interface PerformanceTrace +``` + +## Methods + +| Method | Description | +| --- | --- | +| [getAttribute(attr)](./performance.performancetrace.md#performancetracegetattribute) | Retrieves the value which a custom attribute is set to. | +| [getAttributes()](./performance.performancetrace.md#performancetracegetattributes) | Returns a map of all custom attributes of a trace instance. | +| [getMetric(metricName)](./performance.performancetrace.md#performancetracegetmetric) | Returns the value of the custom metric by that name. If a custom metric with that name does not exist will return zero. | +| [incrementMetric(metricName, num)](./performance.performancetrace.md#performancetraceincrementmetric) | Adds to the value of a custom metric. If a custom metric with the provided name does not exist, it creates one with that name and the value equal to the given number. The value will be floored down to an integer. | +| [putAttribute(attr, value)](./performance.performancetrace.md#performancetraceputattribute) | Set a custom attribute of a trace to a certain value. | +| [putMetric(metricName, num)](./performance.performancetrace.md#performancetraceputmetric) | Sets the value of the specified custom metric to the given number regardless of whether a metric with that name already exists on the trace instance or not. The value will be floored down to an integer. | +| [record(startTime, duration, options)](./performance.performancetrace.md#performancetracerecord) | Records a trace from given parameters. This provides a direct way to use trace without a need to start/stop. This is useful for use cases in which the trace cannot directly be used (e.g. if the duration was captured before the Performance SDK was loaded). | +| [removeAttribute(attr)](./performance.performancetrace.md#performancetraceremoveattribute) | Removes the specified custom attribute from a trace instance. | +| [start()](./performance.performancetrace.md#performancetracestart) | Starts the timing for the trace instance. | +| [stop()](./performance.performancetrace.md#performancetracestop) | Stops the timing of the trace instance and logs the data of the instance. | + +## PerformanceTrace.getAttribute() + +Retrieves the value which a custom attribute is set to. + +Signature: + +```typescript +getAttribute(attr: string): string | undefined; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| attr | string | Name of the custom attribute. | + +Returns: + +string \| undefined + +## PerformanceTrace.getAttributes() + +Returns a map of all custom attributes of a trace instance. + +Signature: + +```typescript +getAttributes(): { + [key: string]: string; + }; +``` +Returns: + +{ \[key: string\]: string; } + +## PerformanceTrace.getMetric() + +Returns the value of the custom metric by that name. If a custom metric with that name does not exist will return zero. + +Signature: + +```typescript +getMetric(metricName: string): number; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| metricName | string | Name of the custom metric. | + +Returns: + +number + +## PerformanceTrace.incrementMetric() + +Adds to the value of a custom metric. If a custom metric with the provided name does not exist, it creates one with that name and the value equal to the given number. The value will be floored down to an integer. + +Signature: + +```typescript +incrementMetric(metricName: string, num?: number): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| metricName | string | The name of the custom metric. | +| num | number | The number to be added to the value of the custom metric. If not provided, it uses a default value of one. | + +Returns: + +void + +## PerformanceTrace.putAttribute() + +Set a custom attribute of a trace to a certain value. + +Signature: + +```typescript +putAttribute(attr: string, value: string): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| attr | string | Name of the custom attribute. | +| value | string | Value of the custom attribute. | + +Returns: + +void + +## PerformanceTrace.putMetric() + +Sets the value of the specified custom metric to the given number regardless of whether a metric with that name already exists on the trace instance or not. The value will be floored down to an integer. + +Signature: + +```typescript +putMetric(metricName: string, num: number): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| metricName | string | Name of the custom metric. | +| num | number | Value to of the custom metric. | + +Returns: + +void + +## PerformanceTrace.record() + +Records a trace from given parameters. This provides a direct way to use trace without a need to start/stop. This is useful for use cases in which the trace cannot directly be used (e.g. if the duration was captured before the Performance SDK was loaded). + +Signature: + +```typescript +record(startTime: number, duration: number, options?: { + metrics?: { + [key: string]: number; + }; + attributes?: { + [key: string]: string; + }; + }): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| startTime | number | trace start time since epoch in millisec. | +| duration | number | The duraction of the trace in millisec. | +| options | { metrics?: { \[key: string\]: number; }; attributes?: { \[key: string\]: string; }; } | An object which can optionally hold maps of custom metrics and custom attributes. | + +Returns: + +void + +## PerformanceTrace.removeAttribute() + +Removes the specified custom attribute from a trace instance. + +Signature: + +```typescript +removeAttribute(attr: string): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| attr | string | Name of the custom attribute. | + +Returns: + +void + +## PerformanceTrace.start() + +Starts the timing for the trace instance. + +Signature: + +```typescript +start(): void; +``` +Returns: + +void + +## PerformanceTrace.stop() + +Stops the timing of the trace instance and logs the data of the instance. + +Signature: + +```typescript +stop(): void; +``` +Returns: + +void + diff --git a/docs-devsite/remote-config.md b/docs-devsite/remote-config.md new file mode 100644 index 00000000000..5011c3b12b9 --- /dev/null +++ b/docs-devsite/remote-config.md @@ -0,0 +1,345 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# remote-config package +Firebase Remote Config + +## Functions + +| Function | Description | +| --- | --- | +| function(app...) | +| [getRemoteConfig(app)](./remote-config.md#getremoteconfig) | | +| function(remoteConfig...) | +| [activate(remoteConfig)](./remote-config.md#activate) | Makes the last fetched config available to the getters. | +| [ensureInitialized(remoteConfig)](./remote-config.md#ensureinitialized) | Ensures the last activated config are available to the getters. | +| [fetchAndActivate(remoteConfig)](./remote-config.md#fetchandactivate) | Performs fetch and activate operations, as a convenience. | +| [fetchConfig(remoteConfig)](./remote-config.md#fetchconfig) | Fetches and caches configuration from the Remote Config service. | +| [getAll(remoteConfig)](./remote-config.md#getall) | Gets all config. | +| [getBoolean(remoteConfig, key)](./remote-config.md#getboolean) | Gets the value for the given key as a boolean.Convenience method for calling remoteConfig.getValue(key).asBoolean(). | +| [getNumber(remoteConfig, key)](./remote-config.md#getnumber) | Gets the value for the given key as a number.Convenience method for calling remoteConfig.getValue(key).asNumber(). | +| [getString(remoteConfig, key)](./remote-config.md#getstring) | Gets the value for the given key as a string. Convenience method for calling remoteConfig.getValue(key).asString(). | +| [getValue(remoteConfig, key)](./remote-config.md#getvalue) | Gets the [Value](./remote-config.value.md#value_interface) for the given key. | +| [setLogLevel(remoteConfig, logLevel)](./remote-config.md#setloglevel) | Defines the log level to use. | +| function() | +| [isSupported()](./remote-config.md#issupported) | This method provides two different checks:1. Check if IndexedDB exists in the browser environment. 2. Check if the current browser context allows IndexedDB open() calls. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The Firebase Remote Config service interface. | +| [RemoteConfigSettings](./remote-config.remoteconfigsettings.md#remoteconfigsettings_interface) | Defines configuration options for the Remote Config SDK. | +| [Value](./remote-config.value.md#value_interface) | Wraps a value with metadata and type-safe getters. | + +## Type Aliases + +| Type Alias | Description | +| --- | --- | +| [FetchStatus](./remote-config.md#fetchstatus) | Summarizes the outcome of the last attempt to fetch config from the Firebase Remote Config server.
  • "no-fetch-yet" indicates the [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance has not yet attempted to fetch config, or that SDK initialization is incomplete.
  • "success" indicates the last attempt succeeded.
  • "failure" indicates the last attempt failed.
  • "throttle" indicates the last attempt was rate-limited.
| +| [LogLevel](./remote-config.md#loglevel) | Defines levels of Remote Config logging. | +| [ValueSource](./remote-config.md#valuesource) | Indicates the source of a value.
  • "static" indicates the value was defined by a static constant.
  • "default" indicates the value was defined by default config.
  • "remote" indicates the value was defined by fetched config.
| + +## getRemoteConfig() + +Signature: + +```typescript +export declare function getRemoteConfig(app?: FirebaseApp): RemoteConfig; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance. | + +Returns: + +[RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) + +A [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. + +## activate() + +Makes the last fetched config available to the getters. + +Signature: + +```typescript +export declare function activate(remoteConfig: RemoteConfig): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | + +Returns: + +Promise<boolean> + +A `Promise` which resolves to true if the current call activated the fetched configs. If the fetched configs were already activated, the `Promise` will resolve to false. + +## ensureInitialized() + +Ensures the last activated config are available to the getters. + +Signature: + +```typescript +export declare function ensureInitialized(remoteConfig: RemoteConfig): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | + +Returns: + +Promise<void> + +A `Promise` that resolves when the last activated config is available to the getters. + +## fetchAndActivate() + +Performs fetch and activate operations, as a convenience. + +Signature: + +```typescript +export declare function fetchAndActivate(remoteConfig: RemoteConfig): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | + +Returns: + +Promise<boolean> + +A `Promise` which resolves to true if the current call activated the fetched configs. If the fetched configs were already activated, the `Promise` will resolve to false. + +## fetchConfig() + +Fetches and caches configuration from the Remote Config service. + +Signature: + +```typescript +export declare function fetchConfig(remoteConfig: RemoteConfig): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | + +Returns: + +Promise<void> + +## getAll() + +Gets all config. + +Signature: + +```typescript +export declare function getAll(remoteConfig: RemoteConfig): Record; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | + +Returns: + +Record<string, [Value](./remote-config.value.md#value_interface)> + +All config. + +## getBoolean() + +Gets the value for the given key as a boolean. + +Convenience method for calling remoteConfig.getValue(key).asBoolean(). + +Signature: + +```typescript +export declare function getBoolean(remoteConfig: RemoteConfig, key: string): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | +| key | string | The name of the parameter. | + +Returns: + +boolean + +The value for the given key as a boolean. + +## getNumber() + +Gets the value for the given key as a number. + +Convenience method for calling remoteConfig.getValue(key).asNumber(). + +Signature: + +```typescript +export declare function getNumber(remoteConfig: RemoteConfig, key: string): number; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | +| key | string | The name of the parameter. | + +Returns: + +number + +The value for the given key as a number. + +## getString() + +Gets the value for the given key as a string. Convenience method for calling remoteConfig.getValue(key).asString(). + +Signature: + +```typescript +export declare function getString(remoteConfig: RemoteConfig, key: string): string; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | +| key | string | The name of the parameter. | + +Returns: + +string + +The value for the given key as a string. + +## getValue() + +Gets the [Value](./remote-config.value.md#value_interface) for the given key. + +Signature: + +```typescript +export declare function getValue(remoteConfig: RemoteConfig, key: string): Value; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | +| key | string | The name of the parameter. | + +Returns: + +[Value](./remote-config.value.md#value_interface) + +The value for the given key. + +## setLogLevel() + +Defines the log level to use. + +Signature: + +```typescript +export declare function setLogLevel(remoteConfig: RemoteConfig, logLevel: RemoteConfigLogLevel): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. | +| logLevel | [RemoteConfigLogLevel](./remote-config.md#loglevel) | The log level to set. | + +Returns: + +void + +## isSupported() + +This method provides two different checks: + +1. Check if IndexedDB exists in the browser environment. 2. Check if the current browser context allows IndexedDB `open()` calls. + +Signature: + +```typescript +export declare function isSupported(): Promise; +``` +Returns: + +Promise<boolean> + +A `Promise` which resolves to true if a [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance can be initialized in this environment, or false if it cannot. + +## FetchStatus + +Summarizes the outcome of the last attempt to fetch config from the Firebase Remote Config server. + +
  • "no-fetch-yet" indicates the [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance has not yet attempted to fetch config, or that SDK initialization is incomplete.
  • "success" indicates the last attempt succeeded.
  • "failure" indicates the last attempt failed.
  • "throttle" indicates the last attempt was rate-limited.
+ +Signature: + +```typescript +export declare type FetchStatus = 'no-fetch-yet' | 'success' | 'failure' | 'throttle'; +``` + +## LogLevel + +Defines levels of Remote Config logging. + +Signature: + +```typescript +export declare type LogLevel = 'debug' | 'error' | 'silent'; +``` + +## ValueSource + +Indicates the source of a value. + +
  • "static" indicates the value was defined by a static constant.
  • "default" indicates the value was defined by default config.
  • "remote" indicates the value was defined by fetched config.
+ +Signature: + +```typescript +export declare type ValueSource = 'static' | 'default' | 'remote'; +``` diff --git a/docs-devsite/remote-config.remoteconfig.md b/docs-devsite/remote-config.remoteconfig.md new file mode 100644 index 00000000000..3f4f0688b13 --- /dev/null +++ b/docs-devsite/remote-config.remoteconfig.md @@ -0,0 +1,81 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# RemoteConfig interface +The Firebase Remote Config service interface. + +Signature: + +```typescript +export interface RemoteConfig +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [app](./remote-config.remoteconfig.md#remoteconfigapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this RemoteConfig instance is associated with. | +| [defaultConfig](./remote-config.remoteconfig.md#remoteconfigdefaultconfig) | { \[key: string\]: string \| number \| boolean; } | Object containing default values for configs. | +| [fetchTimeMillis](./remote-config.remoteconfig.md#remoteconfigfetchtimemillis) | number | The Unix timestamp in milliseconds of the last successful fetch, or negative one if the [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance either hasn't fetched or initialization is incomplete. | +| [lastFetchStatus](./remote-config.remoteconfig.md#remoteconfiglastfetchstatus) | [FetchStatus](./remote-config.md#fetchstatus) | The status of the last fetch attempt. | +| [settings](./remote-config.remoteconfig.md#remoteconfigsettings) | [RemoteConfigSettings](./remote-config.remoteconfigsettings.md#remoteconfigsettings_interface) | Defines configuration for the Remote Config SDK. | + +## RemoteConfig.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) this `RemoteConfig` instance is associated with. + +Signature: + +```typescript +app: FirebaseApp; +``` + +## RemoteConfig.defaultConfig + +Object containing default values for configs. + +Signature: + +```typescript +defaultConfig: { + [key: string]: string | number | boolean; + }; +``` + +## RemoteConfig.fetchTimeMillis + +The Unix timestamp in milliseconds of the last successful fetch, or negative one if the [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance either hasn't fetched or initialization is incomplete. + +Signature: + +```typescript +fetchTimeMillis: number; +``` + +## RemoteConfig.lastFetchStatus + +The status of the last fetch attempt. + +Signature: + +```typescript +lastFetchStatus: FetchStatus; +``` + +## RemoteConfig.settings + +Defines configuration for the Remote Config SDK. + +Signature: + +```typescript +settings: RemoteConfigSettings; +``` diff --git a/docs-devsite/remote-config.remoteconfigsettings.md b/docs-devsite/remote-config.remoteconfigsettings.md new file mode 100644 index 00000000000..58e505ad863 --- /dev/null +++ b/docs-devsite/remote-config.remoteconfigsettings.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# RemoteConfigSettings interface +Defines configuration options for the Remote Config SDK. + +Signature: + +```typescript +export interface RemoteConfigSettings +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [fetchTimeoutMillis](./remote-config.remoteconfigsettings.md#remoteconfigsettingsfetchtimeoutmillis) | number | Defines the maximum amount of milliseconds to wait for a response when fetching configuration from the Remote Config server. Defaults to 60000 (One minute). | +| [minimumFetchIntervalMillis](./remote-config.remoteconfigsettings.md#remoteconfigsettingsminimumfetchintervalmillis) | number | Defines the maximum age in milliseconds of an entry in the config cache before it is considered stale. Defaults to 43200000 (Twelve hours). | + +## RemoteConfigSettings.fetchTimeoutMillis + +Defines the maximum amount of milliseconds to wait for a response when fetching configuration from the Remote Config server. Defaults to 60000 (One minute). + +Signature: + +```typescript +fetchTimeoutMillis: number; +``` + +## RemoteConfigSettings.minimumFetchIntervalMillis + +Defines the maximum age in milliseconds of an entry in the config cache before it is considered stale. Defaults to 43200000 (Twelve hours). + +Signature: + +```typescript +minimumFetchIntervalMillis: number; +``` diff --git a/docs-devsite/remote-config.value.md b/docs-devsite/remote-config.value.md new file mode 100644 index 00000000000..36fb492d524 --- /dev/null +++ b/docs-devsite/remote-config.value.md @@ -0,0 +1,83 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# Value interface +Wraps a value with metadata and type-safe getters. + +Signature: + +```typescript +export interface Value +``` + +## Methods + +| Method | Description | +| --- | --- | +| [asBoolean()](./remote-config.value.md#valueasboolean) | Gets the value as a boolean.The following values (case insensitive) are interpreted as true: "1", "true", "t", "yes", "y", "on". Other values are interpreted as false. | +| [asNumber()](./remote-config.value.md#valueasnumber) | Gets the value as a number. Comparable to calling Number(value) \|\| 0. | +| [asString()](./remote-config.value.md#valueasstring) | Gets the value as a string. | +| [getSource()](./remote-config.value.md#valuegetsource) | Gets the [ValueSource](./remote-config.md#valuesource) for the given key. | + +## Value.asBoolean() + +Gets the value as a boolean. + +The following values (case insensitive) are interpreted as true: "1", "true", "t", "yes", "y", "on". Other values are interpreted as false. + +Signature: + +```typescript +asBoolean(): boolean; +``` +Returns: + +boolean + +## Value.asNumber() + +Gets the value as a number. Comparable to calling Number(value) \|\| 0. + +Signature: + +```typescript +asNumber(): number; +``` +Returns: + +number + +## Value.asString() + +Gets the value as a string. + +Signature: + +```typescript +asString(): string; +``` +Returns: + +string + +## Value.getSource() + +Gets the [ValueSource](./remote-config.md#valuesource) for the given key. + +Signature: + +```typescript +getSource(): ValueSource; +``` +Returns: + +[ValueSource](./remote-config.md#valuesource) + diff --git a/docs-devsite/storage.firebasestorage.md b/docs-devsite/storage.firebasestorage.md new file mode 100644 index 00000000000..a44df8bfc3d --- /dev/null +++ b/docs-devsite/storage.firebasestorage.md @@ -0,0 +1,58 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FirebaseStorage interface +A Firebase Storage instance. + +Signature: + +```typescript +export interface FirebaseStorage extends _FirebaseService +``` +Extends: \_FirebaseService + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [app](./storage.firebasestorage.md#firebasestorageapp) | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this FirebaseStorage instance. | +| [maxOperationRetryTime](./storage.firebasestorage.md#firebasestoragemaxoperationretrytime) | number | The maximum time to retry operations other than uploads or downloads in milliseconds. | +| [maxUploadRetryTime](./storage.firebasestorage.md#firebasestoragemaxuploadretrytime) | number | The maximum time to retry uploads in milliseconds. | + +## FirebaseStorage.app + +The [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) associated with this `FirebaseStorage` instance. + +Signature: + +```typescript +readonly app: FirebaseApp; +``` + +## FirebaseStorage.maxOperationRetryTime + +The maximum time to retry operations other than uploads or downloads in milliseconds. + +Signature: + +```typescript +maxOperationRetryTime: number; +``` + +## FirebaseStorage.maxUploadRetryTime + +The maximum time to retry uploads in milliseconds. + +Signature: + +```typescript +maxUploadRetryTime: number; +``` diff --git a/docs-devsite/storage.fullmetadata.md b/docs-devsite/storage.fullmetadata.md new file mode 100644 index 00000000000..ca8d66e08d5 --- /dev/null +++ b/docs-devsite/storage.fullmetadata.md @@ -0,0 +1,135 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# FullMetadata interface +The full set of object metadata, including read-only properties. + +Signature: + +```typescript +export interface FullMetadata extends UploadMetadata +``` +Extends: [UploadMetadata](./storage.uploadmetadata.md#uploadmetadata_interface) + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [bucket](./storage.fullmetadata.md#fullmetadatabucket) | string | The bucket this object is contained in. | +| [downloadTokens](./storage.fullmetadata.md#fullmetadatadownloadtokens) | string\[\] \| undefined | Tokens to allow access to the downloatd URL. | +| [fullPath](./storage.fullmetadata.md#fullmetadatafullpath) | string | The full path of this object. | +| [generation](./storage.fullmetadata.md#fullmetadatageneration) | string | The object's generation. [https://cloud.google.com/storage/docs/metadata\#generation-number](https://cloud.google.com/storage/docs/metadata#generation-number) | +| [metageneration](./storage.fullmetadata.md#fullmetadatametageneration) | string | The object's metageneration. [https://cloud.google.com/storage/docs/metadata\#generation-number](https://cloud.google.com/storage/docs/metadata#generation-number) | +| [name](./storage.fullmetadata.md#fullmetadataname) | string | The short name of this object, which is the last component of the full path. For example, if fullPath is 'full/path/image.png', name is 'image.png'. | +| [ref](./storage.fullmetadata.md#fullmetadataref) | [StorageReference](./storage.storagereference.md#storagereference_interface) \| undefined | StorageReference associated with this upload. | +| [size](./storage.fullmetadata.md#fullmetadatasize) | number | The size of this object, in bytes. | +| [timeCreated](./storage.fullmetadata.md#fullmetadatatimecreated) | string | A date string representing when this object was created. | +| [updated](./storage.fullmetadata.md#fullmetadataupdated) | string | A date string representing when this object was last updated. | + +## FullMetadata.bucket + +The bucket this object is contained in. + +Signature: + +```typescript +bucket: string; +``` + +## FullMetadata.downloadTokens + +Tokens to allow access to the downloatd URL. + +Signature: + +```typescript +downloadTokens: string[] | undefined; +``` + +## FullMetadata.fullPath + +The full path of this object. + +Signature: + +```typescript +fullPath: string; +``` + +## FullMetadata.generation + +The object's generation. [https://cloud.google.com/storage/docs/metadata\#generation-number](https://cloud.google.com/storage/docs/metadata#generation-number) + +Signature: + +```typescript +generation: string; +``` + +## FullMetadata.metageneration + +The object's metageneration. [https://cloud.google.com/storage/docs/metadata\#generation-number](https://cloud.google.com/storage/docs/metadata#generation-number) + +Signature: + +```typescript +metageneration: string; +``` + +## FullMetadata.name + +The short name of this object, which is the last component of the full path. For example, if fullPath is 'full/path/image.png', name is 'image.png'. + +Signature: + +```typescript +name: string; +``` + +## FullMetadata.ref + +`StorageReference` associated with this upload. + +Signature: + +```typescript +ref?: StorageReference | undefined; +``` + +## FullMetadata.size + +The size of this object, in bytes. + +Signature: + +```typescript +size: number; +``` + +## FullMetadata.timeCreated + +A date string representing when this object was created. + +Signature: + +```typescript +timeCreated: string; +``` + +## FullMetadata.updated + +A date string representing when this object was last updated. + +Signature: + +```typescript +updated: string; +``` diff --git a/docs-devsite/storage.listoptions.md b/docs-devsite/storage.listoptions.md new file mode 100644 index 00000000000..3f2e92bc639 --- /dev/null +++ b/docs-devsite/storage.listoptions.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ListOptions interface +The options `list()` accepts. + +Signature: + +```typescript +export interface ListOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [maxResults](./storage.listoptions.md#listoptionsmaxresults) | number \| null | If set, limits the total number of prefixes and items to return. The default and maximum maxResults is 1000. | +| [pageToken](./storage.listoptions.md#listoptionspagetoken) | string \| null | The nextPageToken from a previous call to list(). If provided, listing is resumed from the previous position. | + +## ListOptions.maxResults + +If set, limits the total number of `prefixes` and `items` to return. The default and maximum maxResults is 1000. + +Signature: + +```typescript +maxResults?: number | null; +``` + +## ListOptions.pageToken + +The `nextPageToken` from a previous call to `list()`. If provided, listing is resumed from the previous position. + +Signature: + +```typescript +pageToken?: string | null; +``` diff --git a/docs-devsite/storage.listresult.md b/docs-devsite/storage.listresult.md new file mode 100644 index 00000000000..b53a61d92db --- /dev/null +++ b/docs-devsite/storage.listresult.md @@ -0,0 +1,59 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ListResult interface +Result returned by list(). + +Signature: + +```typescript +export interface ListResult +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [items](./storage.listresult.md#listresultitems) | [StorageReference](./storage.storagereference.md#storagereference_interface)\[\] | Objects in this directory. You can call getMetadata() and getDownloadUrl() on them. | +| [nextPageToken](./storage.listresult.md#listresultnextpagetoken) | string | If set, there might be more results for this list. Use this token to resume the list. | +| [prefixes](./storage.listresult.md#listresultprefixes) | [StorageReference](./storage.storagereference.md#storagereference_interface)\[\] | References to prefixes (sub-folders). You can call list() on them to get its contents.Folders are implicit based on '/' in the object paths. For example, if a bucket has two objects '/a/b/1' and '/a/b/2', list('/a') will return '/a/b' as a prefix. | + +## ListResult.items + +Objects in this directory. You can call getMetadata() and getDownloadUrl() on them. + +Signature: + +```typescript +items: StorageReference[]; +``` + +## ListResult.nextPageToken + +If set, there might be more results for this list. Use this token to resume the list. + +Signature: + +```typescript +nextPageToken?: string; +``` + +## ListResult.prefixes + +References to prefixes (sub-folders). You can call list() on them to get its contents. + +Folders are implicit based on '/' in the object paths. For example, if a bucket has two objects '/a/b/1' and '/a/b/2', list('/a') will return '/a/b' as a prefix. + +Signature: + +```typescript +prefixes: StorageReference[]; +``` diff --git a/docs-devsite/storage.md b/docs-devsite/storage.md new file mode 100644 index 00000000000..0aab0c6a35d --- /dev/null +++ b/docs-devsite/storage.md @@ -0,0 +1,550 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# storage package +Cloud Storage for Firebase + +## Functions + +| Function | Description | +| --- | --- | +| function(app...) | +| [getStorage(app, bucketUrl)](./storage.md#getstorage) | Gets a [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance for the given Firebase app. | +| function(storage...) | +| [connectStorageEmulator(storage, host, port, options)](./storage.md#connectstorageemulator) | Modify this [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance to communicate with the Cloud Storage emulator. | +| [ref(storage, url)](./storage.md#ref) | Returns a [StorageReference](./storage.storagereference.md#storagereference_interface) for the given url. | +| function(ref...) | +| [deleteObject(ref)](./storage.md#deleteobject) | Deletes the object at this location. | +| [getBlob(ref, maxDownloadSizeBytes)](./storage.md#getblob) | Downloads the data at the object's location. Returns an error if the object is not found.To use this functionality, you have to whitelist your app's origin in your Cloud Storage bucket. See also https://cloud.google.com/storage/docs/configuring-corsThis API is not available in Node. | +| [getBytes(ref, maxDownloadSizeBytes)](./storage.md#getbytes) | Downloads the data at the object's location. Returns an error if the object is not found.To use this functionality, you have to whitelist your app's origin in your Cloud Storage bucket. See also https://cloud.google.com/storage/docs/configuring-cors | +| [getDownloadURL(ref)](./storage.md#getdownloadurl) | Returns the download URL for the given [StorageReference](./storage.storagereference.md#storagereference_interface). | +| [getMetadata(ref)](./storage.md#getmetadata) | A Promise that resolves with the metadata for this object. If this object doesn't exist or metadata cannot be retreived, the promise is rejected. | +| [getStream(ref, maxDownloadSizeBytes)](./storage.md#getstream) | Downloads the data at the object's location. Raises an error event if the object is not found.This API is only available in Node. | +| [list(ref, options)](./storage.md#list) | List items (files) and prefixes (folders) under this storage reference.List API is only available for Firebase Rules Version 2.GCS is a key-blob store. Firebase Storage imposes the semantic of '/' delimited folder structure. Refer to GCS's List API if you want to learn more.To adhere to Firebase Rules's Semantics, Firebase Storage does not support objects whose paths end with "/" or contain two consecutive "/"s. Firebase Storage List API will filter these unsupported objects. list() may fail if there are too many unsupported objects in the bucket. | +| [listAll(ref)](./storage.md#listall) | List all items (files) and prefixes (folders) under this storage reference.This is a helper method for calling list() repeatedly until there are no more results. The default pagination size is 1000.Note: The results may not be consistent if objects are changed while this operation is running.Warning: listAll may potentially consume too many resources if there are too many results. | +| [updateMetadata(ref, metadata)](./storage.md#updatemetadata) | Updates the metadata for this object. | +| [uploadBytes(ref, data, metadata)](./storage.md#uploadbytes) | Uploads data to this object's location. The upload is not resumable. | +| [uploadBytesResumable(ref, data, metadata)](./storage.md#uploadbytesresumable) | Uploads data to this object's location. The upload can be paused and resumed, and exposes progress updates. | +| [uploadString(ref, value, format, metadata)](./storage.md#uploadstring) | Uploads a string to this object's location. The upload is not resumable. | +| function(storageOrRef...) | +| [ref(storageOrRef, path)](./storage.md#ref) | Returns a [StorageReference](./storage.storagereference.md#storagereference_interface) for the given path in the default bucket. | + +## Classes + +| Class | Description | +| --- | --- | +| [StorageError](./storage.storageerror.md#storageerror_class) | An error returned by the Firebase Storage SDK. | + +## Enumerations + +| Enumeration | Description | +| --- | --- | +| [StorageErrorCode](./storage.md#storageerrorcode) | Error codes that can be attached to StorageError objects. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) | A Firebase Storage instance. | +| [FullMetadata](./storage.fullmetadata.md#fullmetadata_interface) | The full set of object metadata, including read-only properties. | +| [ListOptions](./storage.listoptions.md#listoptions_interface) | The options list() accepts. | +| [ListResult](./storage.listresult.md#listresult_interface) | Result returned by list(). | +| [SettableMetadata](./storage.settablemetadata.md#settablemetadata_interface) | Object metadata that can be set at any time. | +| [StorageObserver](./storage.storageobserver.md#storageobserver_interface) | A stream observer for Firebase Storage. | +| [StorageReference](./storage.storagereference.md#storagereference_interface) | Represents a reference to a Google Cloud Storage object. Developers can upload, download, and delete objects, as well as get/set object metadata. | +| [UploadMetadata](./storage.uploadmetadata.md#uploadmetadata_interface) | Object metadata that can be set at upload. | +| [UploadResult](./storage.uploadresult.md#uploadresult_interface) | Result returned from a non-resumable upload. | +| [UploadTask](./storage.uploadtask.md#uploadtask_interface) | Represents the process of uploading an object. Allows you to monitor and manage the upload. | +| [UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface) | Holds data about the current state of the upload task. | + +## Variables + +| Variable | Description | +| --- | --- | +| [StringFormat](./storage.md#stringformat) | An enumeration of the possible string formats for upload. | + +## Type Aliases + +| Type Alias | Description | +| --- | --- | +| [StringFormat](./storage.md#stringformat) | An enumeration of the possible string formats for upload. | +| [TaskEvent](./storage.md#taskevent) | An event that is triggered on a task. | +| [TaskState](./storage.md#taskstate) | Represents the current state of a running upload. | + +## getStorage() + +Gets a [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance for the given Firebase app. + +Signature: + +```typescript +export declare function getStorage(app?: FirebaseApp, bucketUrl?: string): FirebaseStorage; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| app | [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | Firebase app to get [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance for. | +| bucketUrl | string | The gs:// url to your Firebase Storage Bucket. If not passed, uses the app's default Storage Bucket. | + +Returns: + +[FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) + +A [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance. + +## connectStorageEmulator() + +Modify this [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance to communicate with the Cloud Storage emulator. + +Signature: + +```typescript +export declare function connectStorageEmulator(storage: FirebaseStorage, host: string, port: number, options?: { + mockUserToken?: EmulatorMockTokenOptions | string; +}): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| storage | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) | The [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance | +| host | string | The emulator host (ex: localhost) | +| port | number | The emulator port (ex: 5001) | +| options | { mockUserToken?: [EmulatorMockTokenOptions](./util.md#emulatormocktokenoptions) \| string; } | Emulator options. options.mockUserToken is the mock auth token to use for unit testing Security Rules. | + +Returns: + +void + +## ref() + +Returns a [StorageReference](./storage.storagereference.md#storagereference_interface) for the given url. + +Signature: + +```typescript +export declare function ref(storage: FirebaseStorage, url?: string): StorageReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| storage | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance. | +| url | string | URL. If empty, returns root reference. | + +Returns: + +[StorageReference](./storage.storagereference.md#storagereference_interface) + +## deleteObject() + +Deletes the object at this location. + +Signature: + +```typescript +export declare function deleteObject(ref: StorageReference): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) for object to delete. | + +Returns: + +Promise<void> + +A `Promise` that resolves if the deletion succeeds. + +## getBlob() + +Downloads the data at the object's location. Returns an error if the object is not found. + +To use this functionality, you have to whitelist your app's origin in your Cloud Storage bucket. See also https://cloud.google.com/storage/docs/configuring-cors + +This API is not available in Node. + +Signature: + +```typescript +export declare function getBlob(ref: StorageReference, maxDownloadSizeBytes?: number): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | StorageReference where data should be downloaded. | +| maxDownloadSizeBytes | number | If set, the maximum allowed size in bytes to retrieve. | + +Returns: + +Promise<Blob> + +A Promise that resolves with a Blob containing the object's bytes + +## getBytes() + +Downloads the data at the object's location. Returns an error if the object is not found. + +To use this functionality, you have to whitelist your app's origin in your Cloud Storage bucket. See also https://cloud.google.com/storage/docs/configuring-cors + +Signature: + +```typescript +export declare function getBytes(ref: StorageReference, maxDownloadSizeBytes?: number): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | StorageReference where data should be downloaded. | +| maxDownloadSizeBytes | number | If set, the maximum allowed size in bytes to retrieve. | + +Returns: + +Promise<ArrayBuffer> + +A Promise containing the object's bytes + +## getDownloadURL() + +Returns the download URL for the given [StorageReference](./storage.storagereference.md#storagereference_interface). + +Signature: + +```typescript +export declare function getDownloadURL(ref: StorageReference): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) to get the download URL for. | + +Returns: + +Promise<string> + +A `Promise` that resolves with the download URL for this object. + +## getMetadata() + +A `Promise` that resolves with the metadata for this object. If this object doesn't exist or metadata cannot be retreived, the promise is rejected. + +Signature: + +```typescript +export declare function getMetadata(ref: StorageReference): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) to get metadata from. | + +Returns: + +Promise<[FullMetadata](./storage.fullmetadata.md#fullmetadata_interface)> + +## getStream() + +Downloads the data at the object's location. Raises an error event if the object is not found. + +This API is only available in Node. + +Signature: + +```typescript +export declare function getStream(ref: StorageReference, maxDownloadSizeBytes?: number): NodeJS.ReadableStream; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | StorageReference where data should be downloaded. | +| maxDownloadSizeBytes | number | If set, the maximum allowed size in bytes to retrieve. | + +Returns: + +NodeJS.ReadableStream + +A stream with the object's data as bytes + +## list() + +List items (files) and prefixes (folders) under this storage reference. + +List API is only available for Firebase Rules Version 2. + +GCS is a key-blob store. Firebase Storage imposes the semantic of '/' delimited folder structure. Refer to GCS's List API if you want to learn more. + +To adhere to Firebase Rules's Semantics, Firebase Storage does not support objects whose paths end with "/" or contain two consecutive "/"s. Firebase Storage List API will filter these unsupported objects. list() may fail if there are too many unsupported objects in the bucket. + +Signature: + +```typescript +export declare function list(ref: StorageReference, options?: ListOptions): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) to get list from. | +| options | [ListOptions](./storage.listoptions.md#listoptions_interface) | See [ListOptions](./storage.listoptions.md#listoptions_interface) for details. | + +Returns: + +Promise<[ListResult](./storage.listresult.md#listresult_interface)> + +A `Promise` that resolves with the items and prefixes. `prefixes` contains references to sub-folders and `items` contains references to objects in this folder. `nextPageToken` can be used to get the rest of the results. + +## listAll() + +List all items (files) and prefixes (folders) under this storage reference. + +This is a helper method for calling list() repeatedly until there are no more results. The default pagination size is 1000. + +Note: The results may not be consistent if objects are changed while this operation is running. + +Warning: `listAll` may potentially consume too many resources if there are too many results. + +Signature: + +```typescript +export declare function listAll(ref: StorageReference): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) to get list from. | + +Returns: + +Promise<[ListResult](./storage.listresult.md#listresult_interface)> + +A `Promise` that resolves with all the items and prefixes under the current storage reference. `prefixes` contains references to sub-directories and `items` contains references to objects in this folder. `nextPageToken` is never returned. + +## updateMetadata() + +Updates the metadata for this object. + +Signature: + +```typescript +export declare function updateMetadata(ref: StorageReference, metadata: SettableMetadata): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) to update metadata for. | +| metadata | [SettableMetadata](./storage.settablemetadata.md#settablemetadata_interface) | The new metadata for the object. Only values that have been explicitly set will be changed. Explicitly setting a value to null will remove the metadata. | + +Returns: + +Promise<[FullMetadata](./storage.fullmetadata.md#fullmetadata_interface)> + +A `Promise` that resolves with the new metadata for this object. + +## uploadBytes() + +Uploads data to this object's location. The upload is not resumable. + +Signature: + +```typescript +export declare function uploadBytes(ref: StorageReference, data: Blob | Uint8Array | ArrayBuffer, metadata?: UploadMetadata): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) where data should be uploaded. | +| data | Blob \| Uint8Array \| ArrayBuffer | The data to upload. | +| metadata | [UploadMetadata](./storage.uploadmetadata.md#uploadmetadata_interface) | Metadata for the data to upload. | + +Returns: + +Promise<[UploadResult](./storage.uploadresult.md#uploadresult_interface)> + +A Promise containing an UploadResult + +## uploadBytesResumable() + +Uploads data to this object's location. The upload can be paused and resumed, and exposes progress updates. + +Signature: + +```typescript +export declare function uploadBytesResumable(ref: StorageReference, data: Blob | Uint8Array | ArrayBuffer, metadata?: UploadMetadata): UploadTask; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) where data should be uploaded. | +| data | Blob \| Uint8Array \| ArrayBuffer | The data to upload. | +| metadata | [UploadMetadata](./storage.uploadmetadata.md#uploadmetadata_interface) | Metadata for the data to upload. | + +Returns: + +[UploadTask](./storage.uploadtask.md#uploadtask_interface) + +An UploadTask + +## uploadString() + +Uploads a string to this object's location. The upload is not resumable. + +Signature: + +```typescript +export declare function uploadString(ref: StorageReference, value: string, format?: StringFormat, metadata?: UploadMetadata): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| ref | [StorageReference](./storage.storagereference.md#storagereference_interface) | [StorageReference](./storage.storagereference.md#storagereference_interface) where string should be uploaded. | +| value | string | The string to upload. | +| format | [StringFormat](./storage.md#stringformat) | The format of the string to upload. | +| metadata | [UploadMetadata](./storage.uploadmetadata.md#uploadmetadata_interface) | Metadata for the string to upload. | + +Returns: + +Promise<[UploadResult](./storage.uploadresult.md#uploadresult_interface)> + +A Promise containing an UploadResult + +## ref() + +Returns a [StorageReference](./storage.storagereference.md#storagereference_interface) for the given path in the default bucket. + +Signature: + +```typescript +export declare function ref(storageOrRef: FirebaseStorage | StorageReference, path?: string): StorageReference; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| storageOrRef | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) \| [StorageReference](./storage.storagereference.md#storagereference_interface) | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) or [StorageReference](./storage.storagereference.md#storagereference_interface). | +| path | string | | + +Returns: + +[StorageReference](./storage.storagereference.md#storagereference_interface) + +## StringFormat + +An enumeration of the possible string formats for upload. + +Signature: + +```typescript +StringFormat: { + readonly RAW: "raw"; + readonly BASE64: "base64"; + readonly BASE64URL: "base64url"; + readonly DATA_URL: "data_url"; +} +``` + +## StringFormat + +An enumeration of the possible string formats for upload. + +Signature: + +```typescript +export declare type StringFormat = typeof StringFormat[keyof typeof StringFormat]; +``` + +## TaskEvent + +An event that is triggered on a task. + +Signature: + +```typescript +export declare type TaskEvent = 'state_changed'; +``` + +## TaskState + +Represents the current state of a running upload. + +Signature: + +```typescript +export declare type TaskState = 'running' | 'paused' | 'success' | 'canceled' | 'error'; +``` + +## StorageErrorCode + +Error codes that can be attached to `StorageError` objects. + +Signature: + +```typescript +export declare enum StorageErrorCode +``` + +## Enumeration Members + +| Member | Value | Description | +| --- | --- | --- | +| APP\_DELETED | "app-deleted" | | +| BUCKET\_NOT\_FOUND | "bucket-not-found" | | +| CANCELED | "canceled" | | +| CANNOT\_SLICE\_BLOB | "cannot-slice-blob" | | +| INTERNAL\_ERROR | "internal-error" | | +| INVALID\_ARGUMENT | "invalid-argument" | | +| INVALID\_ARGUMENT\_COUNT | "invalid-argument-count" | | +| INVALID\_CHECKSUM | "invalid-checksum" | | +| INVALID\_DEFAULT\_BUCKET | "invalid-default-bucket" | | +| INVALID\_EVENT\_NAME | "invalid-event-name" | | +| INVALID\_FORMAT | "invalid-format" | | +| INVALID\_ROOT\_OPERATION | "invalid-root-operation" | | +| INVALID\_URL | "invalid-url" | | +| NO\_DEFAULT\_BUCKET | "no-default-bucket" | | +| NO\_DOWNLOAD\_URL | "no-download-url" | | +| OBJECT\_NOT\_FOUND | "object-not-found" | | +| PROJECT\_NOT\_FOUND | "project-not-found" | | +| QUOTA\_EXCEEDED | "quota-exceeded" | | +| RETRY\_LIMIT\_EXCEEDED | "retry-limit-exceeded" | | +| SERVER\_FILE\_WRONG\_SIZE | "server-file-wrong-size" | | +| UNAUTHENTICATED | "unauthenticated" | | +| UNAUTHORIZED | "unauthorized" | | +| UNAUTHORIZED\_APP | "unauthorized-app" | | +| UNKNOWN | "unknown" | | +| UNSUPPORTED\_ENVIRONMENT | "unsupported-environment" | | + diff --git a/docs-devsite/storage.settablemetadata.md b/docs-devsite/storage.settablemetadata.md new file mode 100644 index 00000000000..c721cc6c4f0 --- /dev/null +++ b/docs-devsite/storage.settablemetadata.md @@ -0,0 +1,92 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# SettableMetadata interface +Object metadata that can be set at any time. + +Signature: + +```typescript +export interface SettableMetadata +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [cacheControl](./storage.settablemetadata.md#settablemetadatacachecontrol) | string \| undefined | Served as the 'Cache-Control' header on object download. | +| [contentDisposition](./storage.settablemetadata.md#settablemetadatacontentdisposition) | string \| undefined | Served as the 'Content-Disposition' header on object download. | +| [contentEncoding](./storage.settablemetadata.md#settablemetadatacontentencoding) | string \| undefined | Served as the 'Content-Encoding' header on object download. | +| [contentLanguage](./storage.settablemetadata.md#settablemetadatacontentlanguage) | string \| undefined | Served as the 'Content-Language' header on object download. | +| [contentType](./storage.settablemetadata.md#settablemetadatacontenttype) | string \| undefined | Served as the 'Content-Type' header on object download. | +| [customMetadata](./storage.settablemetadata.md#settablemetadatacustommetadata) | { \[key: string\]: string; } \| undefined | Additional user-defined custom metadata. | + +## SettableMetadata.cacheControl + +Served as the 'Cache-Control' header on object download. + +Signature: + +```typescript +cacheControl?: string | undefined; +``` + +## SettableMetadata.contentDisposition + +Served as the 'Content-Disposition' header on object download. + +Signature: + +```typescript +contentDisposition?: string | undefined; +``` + +## SettableMetadata.contentEncoding + +Served as the 'Content-Encoding' header on object download. + +Signature: + +```typescript +contentEncoding?: string | undefined; +``` + +## SettableMetadata.contentLanguage + +Served as the 'Content-Language' header on object download. + +Signature: + +```typescript +contentLanguage?: string | undefined; +``` + +## SettableMetadata.contentType + +Served as the 'Content-Type' header on object download. + +Signature: + +```typescript +contentType?: string | undefined; +``` + +## SettableMetadata.customMetadata + +Additional user-defined custom metadata. + +Signature: + +```typescript +customMetadata?: { + [key: string]: string; + } | undefined; +``` diff --git a/docs-devsite/storage.storageerror.md b/docs-devsite/storage.storageerror.md new file mode 100644 index 00000000000..9e460e47db7 --- /dev/null +++ b/docs-devsite/storage.storageerror.md @@ -0,0 +1,113 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# StorageError class +An error returned by the Firebase Storage SDK. + +Signature: + +```typescript +export declare class StorageError extends FirebaseError +``` +Extends: [FirebaseError](./util.firebaseerror.md#firebaseerror_class) + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(code, message, status\_)](./storage.storageerror.md#storageerrorconstructor) | | Constructs a new instance of the StorageError class | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [customData](./storage.storageerror.md#storageerrorcustomdata) | | { serverResponse: string \| null; } | Stores custom error data unique to the StorageError. | +| [serverResponse](./storage.storageerror.md#storageerrorserverresponse) | | null \| string | Optional response message that was added by the server. | +| [status](./storage.storageerror.md#storageerrorstatus) | | number | | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [\_codeEquals(code)](./storage.storageerror.md#storageerror_codeequals) | | Compares a StorageErrorCode against this error's code, filtering out the prefix. | + +## StorageError.(constructor) + +Constructs a new instance of the `StorageError` class + +Signature: + +```typescript +constructor(code: StorageErrorCode, message: string, status_?: number); +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| code | [StorageErrorCode](./storage.md#storageerrorcode) | A StorageErrorCode string to be prefixed with 'storage/' and added to the end of the message. | +| message | string | Error message. | +| status\_ | number | Corresponding HTTP Status Code | + +## StorageError.customData + +Stores custom error data unique to the `StorageError`. + +Signature: + +```typescript +customData: { + serverResponse: string | null; + }; +``` + +## StorageError.serverResponse + +Optional response message that was added by the server. + +Signature: + +```typescript +get serverResponse(): null | string; + +set serverResponse(serverResponse: string | null); +``` + +## StorageError.status + +Signature: + +```typescript +get status(): number; + +set status(status: number); +``` + +## StorageError.\_codeEquals() + +Compares a `StorageErrorCode` against this error's code, filtering out the prefix. + +Signature: + +```typescript +_codeEquals(code: StorageErrorCode): boolean; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| code | [StorageErrorCode](./storage.md#storageerrorcode) | | + +Returns: + +boolean + diff --git a/docs-devsite/storage.storageobserver.md b/docs-devsite/storage.storageobserver.md new file mode 100644 index 00000000000..583ddca7c3d --- /dev/null +++ b/docs-devsite/storage.storageobserver.md @@ -0,0 +1,51 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# StorageObserver interface +A stream observer for Firebase Storage. + +Signature: + +```typescript +export interface StorageObserver +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [complete](./storage.storageobserver.md#storageobservercomplete) | [CompleteFn](./util.md#completefn) \| null | | +| [error](./storage.storageobserver.md#storageobservererror) | (error: [StorageError](./storage.storageerror.md#storageerror_class)) => void \| null | | +| [next](./storage.storageobserver.md#storageobservernext) | [NextFn](./util.md#nextfn)<T> \| null | | + +## StorageObserver.complete + +Signature: + +```typescript +complete?: CompleteFn | null; +``` + +## StorageObserver.error + +Signature: + +```typescript +error?: (error: StorageError) => void | null; +``` + +## StorageObserver.next + +Signature: + +```typescript +next?: NextFn | null; +``` diff --git a/docs-devsite/storage.storagereference.md b/docs-devsite/storage.storagereference.md new file mode 100644 index 00000000000..4b584a428d5 --- /dev/null +++ b/docs-devsite/storage.storagereference.md @@ -0,0 +1,112 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# StorageReference interface +Represents a reference to a Google Cloud Storage object. Developers can upload, download, and delete objects, as well as get/set object metadata. + +Signature: + +```typescript +export interface StorageReference +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [bucket](./storage.storagereference.md#storagereferencebucket) | string | The name of the bucket containing this reference's object. | +| [fullPath](./storage.storagereference.md#storagereferencefullpath) | string | The full path of this object. | +| [name](./storage.storagereference.md#storagereferencename) | string | The short name of this object, which is the last component of the full path. For example, if fullPath is 'full/path/image.png', name is 'image.png'. | +| [parent](./storage.storagereference.md#storagereferenceparent) | [StorageReference](./storage.storagereference.md#storagereference_interface) \| null | A reference pointing to the parent location of this reference, or null if this reference is the root. | +| [root](./storage.storagereference.md#storagereferenceroot) | [StorageReference](./storage.storagereference.md#storagereference_interface) | A reference to the root of this object's bucket. | +| [storage](./storage.storagereference.md#storagereferencestorage) | [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) | The [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance associated with this reference. | + +## Methods + +| Method | Description | +| --- | --- | +| [toString()](./storage.storagereference.md#storagereferencetostring) | Returns a gs:// URL for this object in the form gs://<bucket>/<path>/<to>/<object> | + +## StorageReference.bucket + +The name of the bucket containing this reference's object. + +Signature: + +```typescript +bucket: string; +``` + +## StorageReference.fullPath + +The full path of this object. + +Signature: + +```typescript +fullPath: string; +``` + +## StorageReference.name + +The short name of this object, which is the last component of the full path. For example, if fullPath is 'full/path/image.png', name is 'image.png'. + +Signature: + +```typescript +name: string; +``` + +## StorageReference.parent + +A reference pointing to the parent location of this reference, or null if this reference is the root. + +Signature: + +```typescript +parent: StorageReference | null; +``` + +## StorageReference.root + +A reference to the root of this object's bucket. + +Signature: + +```typescript +root: StorageReference; +``` + +## StorageReference.storage + +The [FirebaseStorage](./storage.firebasestorage.md#firebasestorage_interface) instance associated with this reference. + +Signature: + +```typescript +storage: FirebaseStorage; +``` + +## StorageReference.toString() + +Returns a gs:// URL for this object in the form `gs://///` + +Signature: + +```typescript +toString(): string; +``` +Returns: + +string + +The gs:// URL. + diff --git a/docs-devsite/storage.uploadmetadata.md b/docs-devsite/storage.uploadmetadata.md new file mode 100644 index 00000000000..2b207401736 --- /dev/null +++ b/docs-devsite/storage.uploadmetadata.md @@ -0,0 +1,36 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# UploadMetadata interface +Object metadata that can be set at upload. + +Signature: + +```typescript +export interface UploadMetadata extends SettableMetadata +``` +Extends: [SettableMetadata](./storage.settablemetadata.md#settablemetadata_interface) + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [md5Hash](./storage.uploadmetadata.md#uploadmetadatamd5hash) | string \| undefined | A Base64-encoded MD5 hash of the object being uploaded. | + +## UploadMetadata.md5Hash + +A Base64-encoded MD5 hash of the object being uploaded. + +Signature: + +```typescript +md5Hash?: string | undefined; +``` diff --git a/docs-devsite/storage.uploadresult.md b/docs-devsite/storage.uploadresult.md new file mode 100644 index 00000000000..05e3542ee62 --- /dev/null +++ b/docs-devsite/storage.uploadresult.md @@ -0,0 +1,46 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# UploadResult interface +Result returned from a non-resumable upload. + +Signature: + +```typescript +export interface UploadResult +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [metadata](./storage.uploadresult.md#uploadresultmetadata) | [FullMetadata](./storage.fullmetadata.md#fullmetadata_interface) | Contains the metadata sent back from the server. | +| [ref](./storage.uploadresult.md#uploadresultref) | [StorageReference](./storage.storagereference.md#storagereference_interface) | The reference that spawned this upload. | + +## UploadResult.metadata + +Contains the metadata sent back from the server. + +Signature: + +```typescript +readonly metadata: FullMetadata; +``` + +## UploadResult.ref + +The reference that spawned this upload. + +Signature: + +```typescript +readonly ref: StorageReference; +``` diff --git a/docs-devsite/storage.uploadtask.md b/docs-devsite/storage.uploadtask.md new file mode 100644 index 00000000000..af4bff4088e --- /dev/null +++ b/docs-devsite/storage.uploadtask.md @@ -0,0 +1,255 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# UploadTask interface +Represents the process of uploading an object. Allows you to monitor and manage the upload. + +Signature: + +```typescript +export interface UploadTask +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [snapshot](./storage.uploadtask.md#uploadtasksnapshot) | [UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface) | A snapshot of the current task state. | + +## Methods + +| Method | Description | +| --- | --- | +| [cancel()](./storage.uploadtask.md#uploadtaskcancel) | Cancels a running task. Has no effect on a complete or failed task. | +| [catch(onRejected)](./storage.uploadtask.md#uploadtaskcatch) | Equivalent to calling then(null, onRejected). | +| [on(event, nextOrObserver, error, complete)](./storage.uploadtask.md#uploadtaskon) | Listens for events on this task.Events have three callback functions (referred to as next, error, and complete).If only the event is passed, a function that can be used to register the callbacks is returned. Otherwise, the callbacks are passed after the event.Callbacks can be passed either as three separate arguments or as the next, error, and complete properties of an object. Any of the three callbacks is optional, as long as at least one is specified. In addition, when you add your callbacks, you get a function back. You can call this function to unregister the associated callbacks. | +| [pause()](./storage.uploadtask.md#uploadtaskpause) | Pauses a currently running task. Has no effect on a paused or failed task. | +| [resume()](./storage.uploadtask.md#uploadtaskresume) | Resumes a paused task. Has no effect on a currently running or failed task. | +| [then(onFulfilled, onRejected)](./storage.uploadtask.md#uploadtaskthen) | This object behaves like a Promise, and resolves with its snapshot data when the upload completes. | + +## UploadTask.snapshot + +A snapshot of the current task state. + +Signature: + +```typescript +snapshot: UploadTaskSnapshot; +``` + +## UploadTask.cancel() + +Cancels a running task. Has no effect on a complete or failed task. + +Signature: + +```typescript +cancel(): boolean; +``` +Returns: + +boolean + +True if the cancel had an effect. + +## UploadTask.catch() + +Equivalent to calling `then(null, onRejected)`. + +Signature: + +```typescript +catch(onRejected: (error: StorageError) => unknown): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| onRejected | (error: [StorageError](./storage.storageerror.md#storageerror_class)) => unknown | | + +Returns: + +Promise<unknown> + +## UploadTask.on() + +Listens for events on this task. + +Events have three callback functions (referred to as `next`, `error`, and `complete`). + +If only the event is passed, a function that can be used to register the callbacks is returned. Otherwise, the callbacks are passed after the event. + +Callbacks can be passed either as three separate arguments or as the `next`, `error`, and `complete` properties of an object. Any of the three callbacks is optional, as long as at least one is specified. In addition, when you add your callbacks, you get a function back. You can call this function to unregister the associated callbacks. + +Signature: + +```typescript +on(event: TaskEvent, nextOrObserver?: StorageObserver | null | ((snapshot: UploadTaskSnapshot) => unknown), error?: ((a: StorageError) => unknown) | null, complete?: Unsubscribe | null): Unsubscribe | Subscribe; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| event | [TaskEvent](./storage.md#taskevent) | The type of event to listen for. | +| nextOrObserver | [StorageObserver](./storage.storageobserver.md#storageobserver_interface)<[UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface)> \| null \| ((snapshot: [UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface)) => unknown) | The next function, which gets called for each item in the event stream, or an observer object with some or all of these three properties (next, error, complete). | +| error | ((a: [StorageError](./storage.storageerror.md#storageerror_class)) => unknown) \| null | A function that gets called with a StorageError if the event stream ends due to an error. | +| complete | [Unsubscribe](./util.md#unsubscribe) \| null | | + +Returns: + +[Unsubscribe](./util.md#unsubscribe) \| [Subscribe](./util.subscribe.md#subscribe_interface)<[UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface)> + +If only the event argument is passed, returns a function you can use to add callbacks (see the examples above). If more than just the event argument is passed, returns a function you can call to unregister the callbacks. + +### Example 1 + +\*\*Pass callbacks separately or in an object.\*\* + +```javascript +var next = function(snapshot) {}; +var error = function(error) {}; +var complete = function() {}; + +// The first example. +uploadTask.on( + firebase.storage.TaskEvent.STATE_CHANGED, + next, + error, + complete); + +// This is equivalent to the first example. +uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED, { + 'next': next, + 'error': error, + 'complete': complete +}); + +// This is equivalent to the first example. +var subscribe = uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED); +subscribe(next, error, complete); + +// This is equivalent to the first example. +var subscribe = uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED); +subscribe({ + 'next': next, + 'error': error, + 'complete': complete +}); + +``` + +### Example 2 + +\*\*Any callback is optional.\*\* + +```javascript +// Just listening for completion, this is legal. +uploadTask.on( + firebase.storage.TaskEvent.STATE_CHANGED, + null, + null, + function() { + console.log('upload complete!'); + }); + +// Just listening for progress/state changes, this is legal. +uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED, function(snapshot) { + var percent = snapshot.bytesTransferred / snapshot.totalBytes * 100; + console.log(percent + "% done"); +}); + +// This is also legal. +uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED, { + 'complete': function() { + console.log('upload complete!'); + } +}); + +``` + +### Example 3 + +\*\*Use the returned function to remove callbacks.\*\* + +```javascript +var unsubscribe = uploadTask.on( + firebase.storage.TaskEvent.STATE_CHANGED, + function(snapshot) { + var percent = snapshot.bytesTransferred / snapshot.totalBytes * 100; + console.log(percent + "% done"); + // Stop after receiving one update. + unsubscribe(); + }); + +// This code is equivalent to the above. +var handle = uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED); +unsubscribe = handle(function(snapshot) { + var percent = snapshot.bytesTransferred / snapshot.totalBytes * 100; + console.log(percent + "% done"); + // Stop after receiving one update. + unsubscribe(); +}); + +``` + +## UploadTask.pause() + +Pauses a currently running task. Has no effect on a paused or failed task. + +Signature: + +```typescript +pause(): boolean; +``` +Returns: + +boolean + +True if the operation took effect, false if ignored. + +## UploadTask.resume() + +Resumes a paused task. Has no effect on a currently running or failed task. + +Signature: + +```typescript +resume(): boolean; +``` +Returns: + +boolean + +True if the operation took effect, false if ignored. + +## UploadTask.then() + +This object behaves like a Promise, and resolves with its snapshot data when the upload completes. + +Signature: + +```typescript +then(onFulfilled?: ((snapshot: UploadTaskSnapshot) => unknown) | null, onRejected?: ((error: StorageError) => unknown) | null): Promise; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| onFulfilled | ((snapshot: [UploadTaskSnapshot](./storage.uploadtasksnapshot.md#uploadtasksnapshot_interface)) => unknown) \| null | The fulfillment callback. Promise chaining works as normal. | +| onRejected | ((error: [StorageError](./storage.storageerror.md#storageerror_class)) => unknown) \| null | The rejection callback. | + +Returns: + +Promise<unknown> + diff --git a/docs-devsite/storage.uploadtasksnapshot.md b/docs-devsite/storage.uploadtasksnapshot.md new file mode 100644 index 00000000000..351ff7a2154 --- /dev/null +++ b/docs-devsite/storage.uploadtasksnapshot.md @@ -0,0 +1,90 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# UploadTaskSnapshot interface +Holds data about the current state of the upload task. + +Signature: + +```typescript +export interface UploadTaskSnapshot +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [bytesTransferred](./storage.uploadtasksnapshot.md#uploadtasksnapshotbytestransferred) | number | The number of bytes that have been successfully uploaded so far. | +| [metadata](./storage.uploadtasksnapshot.md#uploadtasksnapshotmetadata) | [FullMetadata](./storage.fullmetadata.md#fullmetadata_interface) | Before the upload completes, contains the metadata sent to the server. After the upload completes, contains the metadata sent back from the server. | +| [ref](./storage.uploadtasksnapshot.md#uploadtasksnapshotref) | [StorageReference](./storage.storagereference.md#storagereference_interface) | The reference that spawned this snapshot's upload task. | +| [state](./storage.uploadtasksnapshot.md#uploadtasksnapshotstate) | [TaskState](./storage.md#taskstate) | The current state of the task. | +| [task](./storage.uploadtasksnapshot.md#uploadtasksnapshottask) | [UploadTask](./storage.uploadtask.md#uploadtask_interface) | The task of which this is a snapshot. | +| [totalBytes](./storage.uploadtasksnapshot.md#uploadtasksnapshottotalbytes) | number | The total number of bytes to be uploaded. | + +## UploadTaskSnapshot.bytesTransferred + +The number of bytes that have been successfully uploaded so far. + +Signature: + +```typescript +bytesTransferred: number; +``` + +## UploadTaskSnapshot.metadata + +Before the upload completes, contains the metadata sent to the server. After the upload completes, contains the metadata sent back from the server. + +Signature: + +```typescript +metadata: FullMetadata; +``` + +## UploadTaskSnapshot.ref + +The reference that spawned this snapshot's upload task. + +Signature: + +```typescript +ref: StorageReference; +``` + +## UploadTaskSnapshot.state + +The current state of the task. + +Signature: + +```typescript +state: TaskState; +``` + +## UploadTaskSnapshot.task + +The task of which this is a snapshot. + +Signature: + +```typescript +task: UploadTask; +``` + +## UploadTaskSnapshot.totalBytes + +The total number of bytes to be uploaded. + +Signature: + +```typescript +totalBytes: number; +``` From 01654a7fd3a471dd819158941337ccb62b21f8d0 Mon Sep 17 00:00:00 2001 From: Christina Holland Date: Mon, 13 Feb 2023 15:27:07 -0800 Subject: [PATCH 09/12] Update with Firestore doc changes --- docs-devsite/firestore_.aggregatefield.md | 4 ++-- docs-devsite/firestore_.aggregatespec.md | 2 +- docs-devsite/firestore_.md | 4 ++-- docs-devsite/firestore_lite.aggregatefield.md | 4 ++-- docs-devsite/firestore_lite.aggregatespec.md | 2 +- docs-devsite/firestore_lite.md | 4 ++-- 6 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs-devsite/firestore_.aggregatefield.md b/docs-devsite/firestore_.aggregatefield.md index 0c3957520b3..9d364a6abcc 100644 --- a/docs-devsite/firestore_.aggregatefield.md +++ b/docs-devsite/firestore_.aggregatefield.md @@ -22,7 +22,7 @@ export declare class AggregateField | Property | Modifiers | Type | Description | | --- | --- | --- | --- | -| [type](./firestore_.aggregatefield.md#aggregatefieldtype) | | string | A type string to uniquely identify instances of this class. | +| [type](./firestore_.aggregatefield.md#aggregatefieldtype) | | (not declared) | A type string to uniquely identify instances of this class. | ## AggregateField.type @@ -31,5 +31,5 @@ A type string to uniquely identify instances of this class. Signature: ```typescript -type: string; +readonly type = "AggregateField"; ``` diff --git a/docs-devsite/firestore_.aggregatespec.md b/docs-devsite/firestore_.aggregatespec.md index be06b6941f3..7b430a4cb70 100644 --- a/docs-devsite/firestore_.aggregatespec.md +++ b/docs-devsite/firestore_.aggregatespec.md @@ -10,7 +10,7 @@ https://github.com/firebase/firebase-js-sdk {% endcomment %} # AggregateSpec interface -A type whose property values are all `AggregateField` objects. +Specifies a set of aggregations and their aliases. Signature: diff --git a/docs-devsite/firestore_.md b/docs-devsite/firestore_.md index 4a5c2dd49b2..058cdd7b281 100644 --- a/docs-devsite/firestore_.md +++ b/docs-devsite/firestore_.md @@ -134,7 +134,7 @@ https://github.com/firebase/firebase-js-sdk | Interface | Description | | --- | --- | -| [AggregateSpec](./firestore_.aggregatespec.md#aggregatespec_interface) | A type whose property values are all AggregateField objects. | +| [AggregateSpec](./firestore_.aggregatespec.md#aggregatespec_interface) | Specifies a set of aggregations and their aliases. | | [DocumentChange](./firestore_.documentchange.md#documentchange_interface) | A DocumentChange represents a change to the documents matching a query. It contains the document affected and the type of change that occurred. | | [DocumentData](./firestore_.documentdata.md#documentdata_interface) | Document data (for use with [setDoc()](./firestore_lite.md#setdoc)) consists of fields mapped to values. | | [FirestoreDataConverter](./firestore_.firestoredataconverter.md#firestoredataconverter_interface) | Converter used by withConverter() to transform user objects of type T into Firestore data.Using the converter allows you to specify generic type arguments when storing and retrieving objects from Firestore. | @@ -1946,7 +1946,7 @@ The union of all `AggregateField` types that are supported by Firestore. Signature: ```typescript -export declare type AggregateFieldType = AggregateField; +export declare type AggregateFieldType = AggregateField; ``` ## AggregateSpecData diff --git a/docs-devsite/firestore_lite.aggregatefield.md b/docs-devsite/firestore_lite.aggregatefield.md index 952b60c9d80..2376c50c41f 100644 --- a/docs-devsite/firestore_lite.aggregatefield.md +++ b/docs-devsite/firestore_lite.aggregatefield.md @@ -22,7 +22,7 @@ export declare class AggregateField | Property | Modifiers | Type | Description | | --- | --- | --- | --- | -| [type](./firestore_lite.aggregatefield.md#aggregatefieldtype) | | string | A type string to uniquely identify instances of this class. | +| [type](./firestore_lite.aggregatefield.md#aggregatefieldtype) | | (not declared) | A type string to uniquely identify instances of this class. | ## AggregateField.type @@ -31,5 +31,5 @@ A type string to uniquely identify instances of this class. Signature: ```typescript -type: string; +readonly type = "AggregateField"; ``` diff --git a/docs-devsite/firestore_lite.aggregatespec.md b/docs-devsite/firestore_lite.aggregatespec.md index be06b6941f3..7b430a4cb70 100644 --- a/docs-devsite/firestore_lite.aggregatespec.md +++ b/docs-devsite/firestore_lite.aggregatespec.md @@ -10,7 +10,7 @@ https://github.com/firebase/firebase-js-sdk {% endcomment %} # AggregateSpec interface -A type whose property values are all `AggregateField` objects. +Specifies a set of aggregations and their aliases. Signature: diff --git a/docs-devsite/firestore_lite.md b/docs-devsite/firestore_lite.md index 3754cda22b7..3dc3dfe2388 100644 --- a/docs-devsite/firestore_lite.md +++ b/docs-devsite/firestore_lite.md @@ -108,7 +108,7 @@ https://github.com/firebase/firebase-js-sdk | Interface | Description | | --- | --- | -| [AggregateSpec](./firestore_lite.aggregatespec.md#aggregatespec_interface) | A type whose property values are all AggregateField objects. | +| [AggregateSpec](./firestore_lite.aggregatespec.md#aggregatespec_interface) | Specifies a set of aggregations and their aliases. | | [DocumentData](./firestore_lite.documentdata.md#documentdata_interface) | Document data (for use with [setDoc()](./firestore_lite.md#setdoc)) consists of fields mapped to values. | | [FirestoreDataConverter](./firestore_lite.firestoredataconverter.md#firestoredataconverter_interface) | Converter used by withConverter() to transform user objects of type T into Firestore data.Using the converter allows you to specify generic type arguments when storing and retrieving objects from Firestore. | | [Settings](./firestore_lite.settings.md#settings_interface) | Specifies custom configurations for your Cloud Firestore instance. You must set these before invoking any other methods. | @@ -1277,7 +1277,7 @@ The union of all `AggregateField` types that are supported by Firestore. Signature: ```typescript -export declare type AggregateFieldType = AggregateField; +export declare type AggregateFieldType = AggregateField; ``` ## AggregateSpecData From 1492e34a8cde70687ddcbeaba781965ab4be28d9 Mon Sep 17 00:00:00 2001 From: Christina Holland Date: Mon, 13 Feb 2023 15:32:59 -0800 Subject: [PATCH 10/12] revert packages/auth/api-extractor.json --- packages/auth/api-extractor.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/auth/api-extractor.json b/packages/auth/api-extractor.json index 06ff1e940cf..bd0dda5cca2 100644 --- a/packages/auth/api-extractor.json +++ b/packages/auth/api-extractor.json @@ -1,6 +1,6 @@ { "extends": "../../config/api-extractor.json", - "mainEntryPointFilePath": "/dist/esm5/index.doc.d.ts", + "mainEntryPointFilePath": "/dist/esm5/index.d.ts", "dtsRollup": { "enabled": true, "untrimmedFilePath": "/dist/.d.ts", From 64fae79df0846661a1c039c4eb83e428ebb8ff62 Mon Sep 17 00:00:00 2001 From: Christina Holland Date: Tue, 14 Feb 2023 09:55:16 -0800 Subject: [PATCH 11/12] yarn format --- scripts/docgen/docgen.ts | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/scripts/docgen/docgen.ts b/scripts/docgen/docgen.ts index 77284fc539b..dfa0788f561 100644 --- a/scripts/docgen/docgen.ts +++ b/scripts/docgen/docgen.ts @@ -151,17 +151,21 @@ async function generateDocs( }); } else { // api-report is run as part of every build - await spawn('yarn', [ - 'lerna', - 'run', - '--scope', - '@firebase/*', - '--ignore', - '@firebase/*-compat', - 'build' - ], { - stdio: 'inherit' - }); + await spawn( + 'yarn', + [ + 'lerna', + 'run', + '--scope', + '@firebase/*', + '--ignore', + '@firebase/*-compat', + 'build' + ], + { + stdio: 'inherit' + } + ); } // Restore original auth api-extractor.json contents. From 707d3ed47eedafd43fbe072aafd1a750af816f8a Mon Sep 17 00:00:00 2001 From: Christina Holland Date: Tue, 21 Feb 2023 11:13:31 -0800 Subject: [PATCH 12/12] Fix auth api report being altered --- .github/workflows/check-docs.yml | 6 ++---- scripts/docgen/docgen.ts | 10 ++++++++++ 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/.github/workflows/check-docs.yml b/.github/workflows/check-docs.yml index 4e97150b2b5..bafc315bdf5 100644 --- a/.github/workflows/check-docs.yml +++ b/.github/workflows/check-docs.yml @@ -21,10 +21,8 @@ jobs: run: yarn - name: Run doc generation (devsite docs) run: yarn docgen devsite - - name: Check for changes (fail if so) - run: | - cd docs-devsite - git diff --exit-code + - name: Check for changes in docs-devsite dir (fail if so) + run: git diff --exit-code docs-devsite - name: Reference documentation needs to be updated. See message below. if: ${{ failure() }} run: echo "Changes in this PR affect the reference docs. Run \`yarn docgen devsite\` locally to regenerate docs and add them to this PR." \ No newline at end of file diff --git a/scripts/docgen/docgen.ts b/scripts/docgen/docgen.ts index dfa0788f561..69224868397 100644 --- a/scripts/docgen/docgen.ts +++ b/scripts/docgen/docgen.ts @@ -136,6 +136,11 @@ async function generateDocs( `${projectRoot}/packages/auth/api-extractor.json`, 'utf8' ); + // Save original auth.md as well. + const authApiReportOriginal = fs.readFileSync( + `${projectRoot}/common/api-review/auth.api.md`, + 'utf8' + ); const authApiConfigModified = authApiConfigOriginal.replace( `"mainEntryPointFilePath": "/dist/esm5/index.d.ts"`, `"mainEntryPointFilePath": "/dist/esm5/index.doc.d.ts"` @@ -173,6 +178,11 @@ async function generateDocs( `${projectRoot}/packages/auth/api-extractor.json`, authApiConfigOriginal ); + // Restore original auth.api.md + fs.writeFileSync( + `${projectRoot}/common/api-review/auth.api.md`, + authApiReportOriginal + ); if (!fs.existsSync(tmpDir)) { fs.mkdirSync(tmpDir);