From e642fc7cd73161adb925d57af086c6f3e1a38d44 Mon Sep 17 00:00:00 2001 From: Christina Holland Date: Fri, 26 May 2023 12:34:51 -0700 Subject: [PATCH] Docs: mark methods and products that don't work in Node (#7276) --- docs-devsite/analytics.md | 2 +- docs-devsite/app-check.md | 4 +- docs-devsite/auth.auth.md | 2 + docs-devsite/auth.md | 28 +++ docs-devsite/auth.phoneauthprovider.md | 2 + .../auth.phonemultifactorgenerator.md | 2 + docs-devsite/auth.recaptchaverifier.md | 2 + docs-devsite/firestore_.firestoresettings.md | 8 +- docs-devsite/firestore_.md | 12 +- .../firestore_.persistencesettings.md | 2 + .../firestore_.persistentcachesettings.md | 2 + docs-devsite/index.md | 12 +- docs-devsite/installations.md | 2 +- docs-devsite/messaging.md | 2 +- docs-devsite/performance.md | 2 +- docs-devsite/remote-config.md | 2 +- package.json | 4 +- packages/analytics/src/index.ts | 3 +- packages/app-check/src/index.ts | 7 +- packages/auth/src/core/index.ts | 4 + packages/auth/src/model/public_types.ts | 2 + .../platform_browser/mfa/assertions/phone.ts | 3 + .../src/platform_browser/popup_redirect.ts | 3 + .../src/platform_browser/providers/phone.ts | 3 + .../recaptcha/recaptcha_verifier.ts | 3 + .../src/platform_browser/strategies/phone.ts | 13 +- .../src/platform_browser/strategies/popup.ts | 6 +- .../platform_browser/strategies/redirect.ts | 9 +- packages/firebase/compat/index.d.ts | 99 ++++---- packages/firestore/src/api/cache_config.ts | 4 + packages/firestore/src/api/database.ts | 2 + packages/firestore/src/api/settings.ts | 6 + packages/installations/src/index.ts | 3 +- packages/messaging/src/index.ts | 3 +- packages/performance/src/index.ts | 3 +- packages/remote-config/src/index.ts | 3 +- .../docgen-compat/content-sources/js/toc.yaml | 2 + .../content-sources/node/HOME.md | 11 - .../content-sources/node/toc.yaml | 212 ------------------ scripts/docgen-compat/generate-docs.js | 91 +------- .../docgen-compat/theme/layouts/default.hbs | 2 +- 41 files changed, 201 insertions(+), 386 deletions(-) delete mode 100644 scripts/docgen-compat/content-sources/node/HOME.md delete mode 100644 scripts/docgen-compat/content-sources/node/toc.yaml diff --git a/docs-devsite/analytics.md b/docs-devsite/analytics.md index a79e6f005d9..8a2ce2d4a31 100644 --- a/docs-devsite/analytics.md +++ b/docs-devsite/analytics.md @@ -10,7 +10,7 @@ https://github.com/firebase/firebase-js-sdk {% endcomment %} # analytics package -Firebase Analytics +The Firebase Analytics Web SDK. This SDK does not work in a Node.js environment. ## Functions diff --git a/docs-devsite/app-check.md b/docs-devsite/app-check.md index da1b06b12fa..1b9e93c1886 100644 --- a/docs-devsite/app-check.md +++ b/docs-devsite/app-check.md @@ -10,7 +10,9 @@ https://github.com/firebase/firebase-js-sdk {% endcomment %} # app-check package -Firebase App Check +The Firebase App Check Web SDK. + +Firebase App Check does not work in a Node.js environment using `ReCaptchaV3Provider` or `ReCaptchaEnterpriseProvider`, but can be used in Node.js if you use `CustomProvider` and write your own attestation method. ## Functions diff --git a/docs-devsite/auth.auth.md b/docs-devsite/auth.auth.md index b8b21c6870c..4f49465a094 100644 --- a/docs-devsite/auth.auth.md +++ b/docs-devsite/auth.auth.md @@ -221,6 +221,8 @@ This will affect the currently saved Auth session and applies this type of persi 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. +This method does not work in a Node.js environment. + Signature: ```typescript diff --git a/docs-devsite/auth.md b/docs-devsite/auth.md index 1d9598ce7cd..9d5a9a9ab58 100644 --- a/docs-devsite/auth.md +++ b/docs-devsite/auth.md @@ -442,6 +442,8 @@ Returns a [UserCredential](./auth.usercredential.md#usercredential_interface) fr 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`. +This method does not work in a Node.js environment. + Signature: ```typescript @@ -497,6 +499,8 @@ If initializeRecaptchaConfig() is not invoked, the auth flow will always start w Thus, by calling this optional method, you will reduce the latency of future auth flows. Loading the reCAPTCHA config early will also enhance the signal collected by reCAPTCHA. +This method does not work in a Node.js environment. + Signature: ```typescript @@ -694,6 +698,8 @@ Changes the type of persistence on the [Auth](./auth.auth.md#auth_interface) ins 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. +This method does not work in a Node.js environment. + Signature: ```typescript @@ -877,6 +883,8 @@ This method sends a code via SMS to the given phone number, and returns a [Confi 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. +This method does not work in a Node.js environment. + Signature: ```typescript @@ -913,6 +921,8 @@ 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. +This method does not work in a Node.js environment. + Signature: ```typescript @@ -953,6 +963,8 @@ 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). +This method does not work in a Node.js environment. + Signature: ```typescript @@ -1204,6 +1216,8 @@ Promise<[UserCredential](./auth.usercredential.md#usercredential_interface)Signature: ```typescript @@ -1228,6 +1242,8 @@ Links the authenticated provider to the user account using a pop-up based OAuth If the linking is successful, the returned result will contain the user and the provider's credential. +This method does not work in a Node.js environment. + Signature: ```typescript @@ -1264,6 +1280,8 @@ Links the [OAuthProvider](./auth.oauthprovider.md#oauthprovider_class) to the us 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). +This method does not work in a Node.js environment. + Signature: ```typescript @@ -1349,6 +1367,8 @@ 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. +This method does not work in a Node.js environment. + Signature: ```typescript @@ -1373,6 +1393,8 @@ Reauthenticates the current user with the specified [OAuthProvider](./auth.oauth If the reauthentication is successful, the returned result will contain the user and the provider's credential. +This method does not work in a Node.js environment. + Signature: ```typescript @@ -1409,6 +1431,8 @@ Reauthenticates the current user with the specified [OAuthProvider](./auth.oauth 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). +This method does not work in a Node.js environment. + Signature: ```typescript @@ -1585,6 +1609,8 @@ Promise<void> Updates the user's phone number. +This method does not work in a Node.js environment. + Signature: ```typescript @@ -1855,6 +1881,8 @@ browserLocalPersistence: Persistence An implementation of [PopupRedirectResolver](./auth.popupredirectresolver.md#popupredirectresolver_interface) suitable for browser based applications. +This method does not work in a Node.js environment. + Signature: ```typescript diff --git a/docs-devsite/auth.phoneauthprovider.md b/docs-devsite/auth.phoneauthprovider.md index 41e743386de..a7f53f744d5 100644 --- a/docs-devsite/auth.phoneauthprovider.md +++ b/docs-devsite/auth.phoneauthprovider.md @@ -12,6 +12,8 @@ https://github.com/firebase/firebase-js-sdk # PhoneAuthProvider class Provider for generating an [PhoneAuthCredential](./auth.phoneauthcredential.md#phoneauthcredential_class). +`PhoneAuthProvider` does not work in a Node.js environment. + Signature: ```typescript diff --git a/docs-devsite/auth.phonemultifactorgenerator.md b/docs-devsite/auth.phonemultifactorgenerator.md index a59d34814bf..71aa17e201e 100644 --- a/docs-devsite/auth.phonemultifactorgenerator.md +++ b/docs-devsite/auth.phonemultifactorgenerator.md @@ -44,6 +44,8 @@ static FACTOR_ID: string; Provides a [PhoneMultiFactorAssertion](./auth.phonemultifactorassertion.md#phonemultifactorassertion_interface) to confirm ownership of the phone second factor. +This method does not work in a Node.js environment. + Signature: ```typescript diff --git a/docs-devsite/auth.recaptchaverifier.md b/docs-devsite/auth.recaptchaverifier.md index 4f32d489aed..34145ac2b27 100644 --- a/docs-devsite/auth.recaptchaverifier.md +++ b/docs-devsite/auth.recaptchaverifier.md @@ -12,6 +12,8 @@ https://github.com/firebase/firebase-js-sdk # RecaptchaVerifier class An [reCAPTCHA](https://www.google.com/recaptcha/)-based application verifier. +`RecaptchaVerifier` does not work in a Node.js environment. + Signature: ```typescript diff --git a/docs-devsite/firestore_.firestoresettings.md b/docs-devsite/firestore_.firestoresettings.md index 6e5415f28db..89444273b64 100644 --- a/docs-devsite/firestore_.firestoresettings.md +++ b/docs-devsite/firestore_.firestoresettings.md @@ -23,8 +23,8 @@ export declare interface FirestoreSettings | Property | Type | Description | | --- | --- | --- | | [cacheSizeBytes](./firestore_.firestoresettings.md#firestoresettingscachesizebytes) | number | NOTE: This field will be deprecated in a future major release. Use cache field instead to specify cache size, and other cache configurations.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.After having had a default value of false since its inception in 2019, the default value of this setting was changed in May 2023 to true in v9.22.0 of the Firebase JavaScript SDK. That is, auto-detection of long polling is now enabled by default. To disable it, set this setting to false, and please open a GitHub issue to share the problems that motivated you disabling long-polling auto-detection. | -| [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. | +| [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.After having had a default value of false since its inception in 2019, the default value of this setting was changed in May 2023 to true in v9.22.0 of the Firebase JavaScript SDK. That is, auto-detection of long polling is now enabled by default. To disable it, set this setting to false, and please open a GitHub issue to share the problems that motivated you disabling long-polling auto-detection.This setting cannot be used in a Node.js environment. | +| [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.This setting cannot be used in a Node.js environment. | | [experimentalLongPollingOptions](./firestore_.firestoresettings.md#firestoresettingsexperimentallongpollingoptions) | [ExperimentalLongPollingOptions](./firestore_.experimentallongpollingoptions.md#experimentallongpollingoptions_interface) | Options that configure the SDK’s underlying network transport (WebChannel) when long-polling is used.These options are only used if experimentalForceLongPolling is true or if experimentalAutoDetectLongPolling is true and the auto-detection determined that long-polling was needed. Otherwise, these options have no effect. | | [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. | @@ -51,6 +51,8 @@ Configures the SDK's underlying transport (WebChannel) to automatically detect i After having had a default value of `false` since its inception in 2019, the default value of this setting was changed in May 2023 to `true` in v9.22.0 of the Firebase JavaScript SDK. That is, auto-detection of long polling is now enabled by default. To disable it, set this setting to `false`, and please open a GitHub issue to share the problems that motivated you disabling long-polling auto-detection. +This setting cannot be used in a Node.js environment. + Signature: ```typescript @@ -63,6 +65,8 @@ Forces the SDK’s underlying network transport (WebChannel) to use long-polling 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. +This setting cannot be used in a Node.js environment. + Signature: ```typescript diff --git a/docs-devsite/firestore_.md b/docs-devsite/firestore_.md index c38b6bb8407..41b85f1f3eb 100644 --- a/docs-devsite/firestore_.md +++ b/docs-devsite/firestore_.md @@ -25,7 +25,7 @@ https://github.com/firebase/firebase-js-sdk | [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. | +| [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.Persistence cannot be used in a Node.js environment. | | [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. | @@ -103,7 +103,7 @@ https://github.com/firebase/firebase-js-sdk | function(settings...) | | [memoryLocalCache(settings)](./firestore_.md#memorylocalcache) | Creates an instance of MemoryLocalCache. The instance can be set to FirestoreSettings.cache to tell the SDK which cache layer to use. | | [memoryLruGarbageCollector(settings)](./firestore_.md#memorylrugarbagecollector) | Creates an instance of MemoryLruGarbageCollector.A target size can be specified as part of the setting parameter. The collector will start deleting documents once the cache size exceeds the given size. The default cache size is 40MB (40 \* 1024 \* 1024 bytes). | -| [persistentLocalCache(settings)](./firestore_.md#persistentlocalcache) | Creates an instance of PersistentLocalCache. The instance can be set to FirestoreSettings.cache to tell the SDK which cache layer to use. | +| [persistentLocalCache(settings)](./firestore_.md#persistentlocalcache) | Creates an instance of PersistentLocalCache. The instance can be set to FirestoreSettings.cache to tell the SDK which cache layer to use.Persistent cache cannot be used in a Node.js environment. | | [persistentSingleTabManager(settings)](./firestore_.md#persistentsingletabmanager) | Creates an instance of PersistentSingleTabManager. | | 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. | @@ -160,8 +160,8 @@ https://github.com/firebase/firebase-js-sdk | [MemoryEagerGarbageCollector](./firestore_.memoryeagergarbagecollector.md#memoryeagergarbagecollector_interface) | A garbage collector deletes documents whenever they are not part of any active queries, and have no local mutations attached to them.This collector tries to ensure lowest memory footprints from the SDK, at the risk of documents not being cached for offline queries or for direct queries to the cache.Use factory function to create an instance of this collector. | | [MemoryLocalCache](./firestore_.memorylocalcache.md#memorylocalcache_interface) | Provides an in-memory cache to the SDK. This is the default cache unless explicitly configured otherwise.To use, create an instance using the factory function , then set the instance to FirestoreSettings.cache and call initializeFirestore using the settings object. | | [MemoryLruGarbageCollector](./firestore_.memorylrugarbagecollector.md#memorylrugarbagecollector_interface) | A garbage collector deletes Least-Recently-Used documents in multiple batches.This collector is configured with a target size, and will only perform collection when the cached documents exceed the target size. It avoids querying backend repeated for the same query or document, at the risk of having a larger memory footprint.Use factory function to create a instance of this collector. | -| [PersistenceSettings](./firestore_.persistencesettings.md#persistencesettings_interface) | Settings that can be passed to enableIndexedDbPersistence() to configure Firestore persistence. | -| [PersistentCacheSettings](./firestore_.persistentcachesettings.md#persistentcachesettings_interface) | An settings object to configure an PersistentLocalCache instance. | +| [PersistenceSettings](./firestore_.persistencesettings.md#persistencesettings_interface) | Settings that can be passed to enableIndexedDbPersistence() to configure Firestore persistence.Persistence cannot be used in a Node.js environment. | +| [PersistentCacheSettings](./firestore_.persistentcachesettings.md#persistentcachesettings_interface) | An settings object to configure an PersistentLocalCache instance.Persistent cache cannot be used in a Node.js environment. | | [PersistentLocalCache](./firestore_.persistentlocalcache.md#persistentlocalcache_interface) | Provides a persistent cache backed by IndexedDb to the SDK.To use, create an instance using the factory function , then set the instance to FirestoreSettings.cache and call initializeFirestore using the settings object. | | [PersistentMultipleTabManager](./firestore_.persistentmultipletabmanager.md#persistentmultipletabmanager_interface) | A tab manager supporting multiple tabs. SDK will synchronize queries and mutations done across all tabs using the SDK. | | [PersistentSingleTabManager](./firestore_.persistentsingletabmanager.md#persistentsingletabmanager_interface) | A tab manager supportting only one tab, no synchronization will be performed across tabs. | @@ -421,6 +421,8 @@ There are several reasons why this can fail, which can be identified by the `cod \* failed-precondition: The app is already open in another browser tab. \* unimplemented: The browser is incompatible with the offline persistence implementation. +Persistence cannot be used in a Node.js environment. + Signature: ```typescript @@ -2009,6 +2011,8 @@ export declare function memoryLruGarbageCollector(settings?: { Creates an instance of `PersistentLocalCache`. The instance can be set to `FirestoreSettings.cache` to tell the SDK which cache layer to use. +Persistent cache cannot be used in a Node.js environment. + Signature: ```typescript diff --git a/docs-devsite/firestore_.persistencesettings.md b/docs-devsite/firestore_.persistencesettings.md index c84cde1ed13..1a8fb2ac49c 100644 --- a/docs-devsite/firestore_.persistencesettings.md +++ b/docs-devsite/firestore_.persistencesettings.md @@ -12,6 +12,8 @@ https://github.com/firebase/firebase-js-sdk # PersistenceSettings interface Settings that can be passed to `enableIndexedDbPersistence()` to configure Firestore persistence. +Persistence cannot be used in a Node.js environment. + Signature: ```typescript diff --git a/docs-devsite/firestore_.persistentcachesettings.md b/docs-devsite/firestore_.persistentcachesettings.md index dd491918894..a32d05e4e8e 100644 --- a/docs-devsite/firestore_.persistentcachesettings.md +++ b/docs-devsite/firestore_.persistentcachesettings.md @@ -12,6 +12,8 @@ https://github.com/firebase/firebase-js-sdk # PersistentCacheSettings interface An settings object to configure an `PersistentLocalCache` instance. +Persistent cache cannot be used in a Node.js environment. + Signature: ```typescript diff --git a/docs-devsite/index.md b/docs-devsite/index.md index e19f70906ef..6a32ccdbaa6 100644 --- a/docs-devsite/index.md +++ b/docs-devsite/index.md @@ -15,16 +15,16 @@ https://github.com/firebase/firebase-js-sdk | Package | Description | | --- | --- | -| [@firebase/analytics](./analytics.md#analytics_package) | Firebase Analytics | +| [@firebase/analytics](./analytics.md#analytics_package) | The Firebase Analytics Web SDK. This SDK does not work in a Node.js environment. | | [@firebase/app](./app.md#app_package) | Firebase App | -| [@firebase/app-check](./app-check.md#app-check_package) | Firebase App Check | +| [@firebase/app-check](./app-check.md#app-check_package) | The Firebase App Check Web SDK. | | [@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/installations](./installations.md#installations_package) | The Firebase Installations Web SDK. This SDK does not work in a Node.js environment. | +| [@firebase/messaging](./messaging.md#messaging_package) | The Firebase Cloud Messaging Web SDK. This SDK does not work in a Node.js environment. | +| [@firebase/performance](./performance.md#performance_package) | The Firebase Performance Monitoring Web SDK. This SDK does not work in a Node.js environment. | +| [@firebase/remote-config](./remote-config.md#remote-config_package) | The Firebase Remote Config Web SDK. This SDK does not work in a Node.js environment. | | [@firebase/storage](./storage.md#storage_package) | Cloud Storage for Firebase | diff --git a/docs-devsite/installations.md b/docs-devsite/installations.md index 1ef8b80b00e..b4999146385 100644 --- a/docs-devsite/installations.md +++ b/docs-devsite/installations.md @@ -10,7 +10,7 @@ https://github.com/firebase/firebase-js-sdk {% endcomment %} # installations package -Firebase Installations +The Firebase Installations Web SDK. This SDK does not work in a Node.js environment. ## Functions diff --git a/docs-devsite/messaging.md b/docs-devsite/messaging.md index ffbdd9ee3d8..992d5b1c0e3 100644 --- a/docs-devsite/messaging.md +++ b/docs-devsite/messaging.md @@ -10,7 +10,7 @@ https://github.com/firebase/firebase-js-sdk {% endcomment %} # messaging package -Firebase Cloud Messaging +The Firebase Cloud Messaging Web SDK. This SDK does not work in a Node.js environment. | Entry Point | Description | | --- | --- | diff --git a/docs-devsite/performance.md b/docs-devsite/performance.md index 247002ed70a..59bd32a5a7e 100644 --- a/docs-devsite/performance.md +++ b/docs-devsite/performance.md @@ -10,7 +10,7 @@ https://github.com/firebase/firebase-js-sdk {% endcomment %} # performance package -Firebase Performance Monitoring +The Firebase Performance Monitoring Web SDK. This SDK does not work in a Node.js environment. ## Functions diff --git a/docs-devsite/remote-config.md b/docs-devsite/remote-config.md index 5011c3b12b9..9cc0287d130 100644 --- a/docs-devsite/remote-config.md +++ b/docs-devsite/remote-config.md @@ -10,7 +10,7 @@ https://github.com/firebase/firebase-js-sdk {% endcomment %} # remote-config package -Firebase Remote Config +The Firebase Remote Config Web SDK. This SDK does not work in a Node.js environment. ## Functions diff --git a/package.json b/package.json index aa38c37fdaa..4655038c45f 100644 --- a/package.json +++ b/package.json @@ -39,9 +39,7 @@ "test:setup": "node tools/config.js", "test:saucelabs": "node scripts/run_saucelabs.js", "docgen": "ts-node-script scripts/docgen/docgen.ts", - "docgen:compat": "yarn docgen:compat:js; yarn docgen:compat:node", - "docgen:compat:js": "node scripts/docgen-compat/generate-docs.js --api js", - "docgen:compat:node": "node scripts/docgen-compat/generate-docs.js --api node", + "docgen:compat": "node scripts/docgen-compat/generate-docs.js --api js", "lint": "lerna run --scope @firebase/* lint", "lint:fix": "lerna run --scope @firebase/* lint:fix", "size-report": "ts-node-script scripts/size_report/report_binary_size.ts", diff --git a/packages/analytics/src/index.ts b/packages/analytics/src/index.ts index 69e024c3311..ed785fba94b 100644 --- a/packages/analytics/src/index.ts +++ b/packages/analytics/src/index.ts @@ -1,5 +1,6 @@ /** - * Firebase Analytics + * The Firebase Analytics Web SDK. + * This SDK does not work in a Node.js environment. * * @packageDocumentation */ diff --git a/packages/app-check/src/index.ts b/packages/app-check/src/index.ts index b01b62eec88..81d7b90067a 100644 --- a/packages/app-check/src/index.ts +++ b/packages/app-check/src/index.ts @@ -1,5 +1,10 @@ /** - * Firebase App Check + * The Firebase App Check Web SDK. + * + * @remarks + * Firebase App Check does not work in a Node.js environment using `ReCaptchaV3Provider` or + * `ReCaptchaEnterpriseProvider`, but can be used in Node.js if you use + * `CustomProvider` and write your own attestation method. * * @packageDocumentation */ diff --git a/packages/auth/src/core/index.ts b/packages/auth/src/core/index.ts index 9d64d554e60..e39dbab52fb 100644 --- a/packages/auth/src/core/index.ts +++ b/packages/auth/src/core/index.ts @@ -44,6 +44,8 @@ export { * 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. * + * This method does not work in a Node.js environment. + * * @example * ```javascript * setPersistence(auth, browserSessionPersistence); @@ -78,6 +80,8 @@ export function setPersistence( * Thus, by calling this optional method, you will reduce the latency of future auth flows. * Loading the reCAPTCHA config early will also enhance the signal collected by reCAPTCHA. * + * This method does not work in a Node.js environment. + * * @example * ```javascript * initializeRecaptchaConfig(auth); diff --git a/packages/auth/src/model/public_types.ts b/packages/auth/src/model/public_types.ts index 52e53c666f5..30f202a1b8e 100644 --- a/packages/auth/src/model/public_types.ts +++ b/packages/auth/src/model/public_types.ts @@ -194,6 +194,8 @@ export interface Auth { * 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. * + * This method does not work in a Node.js environment. + * * @example * ```javascript * auth.setPersistence(browserSessionPersistence); diff --git a/packages/auth/src/platform_browser/mfa/assertions/phone.ts b/packages/auth/src/platform_browser/mfa/assertions/phone.ts index c23ceb687b1..ded3732bff5 100644 --- a/packages/auth/src/platform_browser/mfa/assertions/phone.ts +++ b/packages/auth/src/platform_browser/mfa/assertions/phone.ts @@ -84,6 +84,9 @@ export class PhoneMultiFactorGenerator { /** * Provides a {@link PhoneMultiFactorAssertion} to confirm ownership of the phone second factor. * + * @remarks + * This method does not work in a Node.js environment. + * * @param phoneAuthCredential - A credential provided by {@link PhoneAuthProvider.credential}. * @returns A {@link PhoneMultiFactorAssertion} which can be used with * {@link MultiFactorResolver.resolveSignIn} diff --git a/packages/auth/src/platform_browser/popup_redirect.ts b/packages/auth/src/platform_browser/popup_redirect.ts index 36c3805c4ec..cf1c1160dc4 100644 --- a/packages/auth/src/platform_browser/popup_redirect.ts +++ b/packages/auth/src/platform_browser/popup_redirect.ts @@ -190,6 +190,9 @@ class BrowserPopupRedirectResolver implements PopupRedirectResolverInternal { * An implementation of {@link PopupRedirectResolver} suitable for browser * based applications. * + * @remarks + * This method does not work in a Node.js environment. + * * @public */ export const browserPopupRedirectResolver: PopupRedirectResolver = diff --git a/packages/auth/src/platform_browser/providers/phone.ts b/packages/auth/src/platform_browser/providers/phone.ts index 79d9239b1c3..2b5c0874b70 100644 --- a/packages/auth/src/platform_browser/providers/phone.ts +++ b/packages/auth/src/platform_browser/providers/phone.ts @@ -37,6 +37,9 @@ import { ProviderId, SignInMethod } from '../../model/enums'; /** * Provider for generating an {@link PhoneAuthCredential}. * + * @remarks + * `PhoneAuthProvider` does not work in a Node.js environment. + * * @example * ```javascript * // 'recaptcha-container' is the ID of an element in the DOM. diff --git a/packages/auth/src/platform_browser/recaptcha/recaptcha_verifier.ts b/packages/auth/src/platform_browser/recaptcha/recaptcha_verifier.ts index ddd312908f4..e8966b1daa6 100644 --- a/packages/auth/src/platform_browser/recaptcha/recaptcha_verifier.ts +++ b/packages/auth/src/platform_browser/recaptcha/recaptcha_verifier.ts @@ -44,6 +44,9 @@ type TokenCallback = (token: string) => void; /** * An {@link https://www.google.com/recaptcha/ | reCAPTCHA}-based application verifier. * + * @remarks + * `RecaptchaVerifier` does not work in a Node.js environment. + * * @public */ export class RecaptchaVerifier implements ApplicationVerifierInternal { diff --git a/packages/auth/src/platform_browser/strategies/phone.ts b/packages/auth/src/platform_browser/strategies/phone.ts index 0f924ab7a44..745385c2db9 100644 --- a/packages/auth/src/platform_browser/strategies/phone.ts +++ b/packages/auth/src/platform_browser/strategies/phone.ts @@ -82,6 +82,8 @@ class ConfirmationResultImpl implements ConfirmationResult { * {@link RecaptchaVerifier} (like React Native), but you need to use a * third-party {@link ApplicationVerifier} implementation. * + * This method does not work in a Node.js environment. + * * @example * ```javascript * // 'recaptcha-container' is the ID of an element in the DOM. @@ -116,6 +118,9 @@ export async function signInWithPhoneNumber( /** * Links the user account with the given phone number. * + * @remarks + * This method does not work in a Node.js environment. + * * @param user - The user. * @param phoneNumber - The user's phone number in E.164 format (e.g. +16505550101). * @param appVerifier - The {@link ApplicationVerifier}. @@ -142,7 +147,10 @@ export async function linkWithPhoneNumber( /** * Re-authenticates a user using a fresh phone credential. * - * @remarks Use before operations such as {@link updatePassword} that require tokens from recent sign-in attempts. + * @remarks + * Use before operations such as {@link updatePassword} that require tokens from recent sign-in attempts. + * + * This method does not work in a Node.js environment. * * @param user - The user. * @param phoneNumber - The user's phone number in E.164 format (e.g. +16505550101). @@ -250,6 +258,9 @@ export async function _verifyPhoneNumber( /** * Updates the user's phone number. * + * @remarks + * This method does not work in a Node.js environment. + * * @example * ``` * // 'recaptcha-container' is the ID of an element in the DOM. diff --git a/packages/auth/src/platform_browser/strategies/popup.ts b/packages/auth/src/platform_browser/strategies/popup.ts index c41cd43342a..e47e03cd3f7 100644 --- a/packages/auth/src/platform_browser/strategies/popup.ts +++ b/packages/auth/src/platform_browser/strategies/popup.ts @@ -63,6 +63,8 @@ export const _POLL_WINDOW_CLOSE_TIMEOUT = new Delay(2000, 10000); * 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. * + * This method does not work in a Node.js environment. + * * @example * ```javascript * // Sign in using a popup. @@ -82,7 +84,6 @@ export const _POLL_WINDOW_CLOSE_TIMEOUT = new Delay(2000, 10000); * @param resolver - An instance of {@link PopupRedirectResolver}, optional * if already supplied to {@link initializeAuth} or provided by {@link getAuth}. * - * * @public */ export async function signInWithPopup( @@ -110,6 +111,8 @@ export async function signInWithPopup( * If the reauthentication is successful, the returned result will contain the user and the * provider's credential. * + * This method does not work in a Node.js environment. + * * @example * ```javascript * // Sign in using a popup. @@ -151,6 +154,7 @@ export async function reauthenticateWithPopup( * @remarks * If the linking is successful, the returned result will contain the user and the provider's credential. * + * This method does not work in a Node.js environment. * * @example * ```javascript diff --git a/packages/auth/src/platform_browser/strategies/redirect.ts b/packages/auth/src/platform_browser/strategies/redirect.ts index f85a0d3d8df..8586ea589d2 100644 --- a/packages/auth/src/platform_browser/strategies/redirect.ts +++ b/packages/auth/src/platform_browser/strategies/redirect.ts @@ -45,6 +45,8 @@ import { getModularInstance } from '@firebase/util'; * Follow the {@link https://firebase.google.com/docs/auth/web/redirect-best-practices * | best practices} when using {@link signInWithRedirect}. * + * This method does not work in a Node.js environment. + * * @example * ```javascript * // Sign in using a redirect. @@ -114,6 +116,8 @@ export async function _signInWithRedirect( * Follow the {@link https://firebase.google.com/docs/auth/web/redirect-best-practices * | best practices} when using {@link reauthenticateWithRedirect}. * + * This method does not work in a Node.js environment. + * * @example * ```javascript * // Sign in using a redirect. @@ -181,6 +185,8 @@ export async function _reauthenticateWithRedirect( * Follow the {@link https://firebase.google.com/docs/auth/web/redirect-best-practices * | best practices} when using {@link linkWithRedirect}. * + * This method does not work in a Node.js environment. + * * @example * ```javascript * // Sign in using some other provider. @@ -200,7 +206,6 @@ export async function _reauthenticateWithRedirect( * @param resolver - An instance of {@link PopupRedirectResolver}, optional * if already supplied to {@link initializeAuth} or provided by {@link getAuth}. * - * * @public */ export function linkWithRedirect( @@ -242,6 +247,8 @@ export async function _linkWithRedirect( * 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`. * + * This method does not work in a Node.js environment. + * * @example * ```javascript * // Sign in using a redirect. diff --git a/packages/firebase/compat/index.d.ts b/packages/firebase/compat/index.d.ts index e33ed582dad..f6ce4e5ea05 100644 --- a/packages/firebase/compat/index.d.ts +++ b/packages/firebase/compat/index.d.ts @@ -426,7 +426,7 @@ declare namespace firebase { * console. * * - * @webonly + * This method does not work in a Node.js environment. * * @example * ```javascript @@ -651,7 +651,7 @@ declare namespace firebase { * console. * * - * @webonly + * This method does not work in a Node.js environment. * * @example * ```javascript @@ -701,7 +701,7 @@ declare namespace firebase { * console. * * - * @webonly + * This method does not work in a Node.js environment. * * @param provider The provider to authenticate. * The provider has to be an OAuth provider. Non-OAuth providers like {@link @@ -1237,7 +1237,7 @@ declare namespace firebase { * generating notifications if the push message payload has a `notification` * parameter. * - * @webonly + * The Messaging SDK does not work in a Node.js environment. * * @example * ```javascript @@ -1296,7 +1296,7 @@ declare namespace firebase { * The {@link firebase.performance.Performance `Performance`} service does not work with * any other app. * - * @webonly + * The Performance SDK does not work in a Node.js environment. * * @example * ```javascript @@ -1315,7 +1315,7 @@ declare namespace firebase { /** * Gets the {@link firebase.remoteConfig.RemoteConfig `RemoteConfig`} instance. * - * @webonly + * The Remote Config SDK does not work in a Node.js environment. * * @example * ```javascript @@ -1335,7 +1335,7 @@ declare namespace firebase { * `firebase.analytics()` can be called with no arguments to access the default * app's {@link firebase.analytics.Analytics `Analytics`} service. * - * @webonly + * The Analytics SDK does not work in a Node.js environment. * * @example * ```javascript @@ -1404,7 +1404,7 @@ declare namespace firebase.app { * Gets the {@link firebase.installations.Installations `Installations`} service for the * current app. * - * @webonly + * The Installations SDK does not work in a Node.js environment. * * @example * ```javascript @@ -1418,7 +1418,7 @@ declare namespace firebase.app { * Gets the {@link firebase.messaging.Messaging `Messaging`} service for the * current app. * - * @webonly + * The Messaging SDK does not work in a Node.js environment. * * @example * ```javascript @@ -1490,7 +1490,7 @@ declare namespace firebase.app { * Gets the {@link firebase.performance.Performance `Performance`} service for the * current app. If the current app is not the default one, throws an error. * - * @webonly + * The Performance SDK does not work in a Node.js environment. * * @example * ```javascript @@ -1503,7 +1503,7 @@ declare namespace firebase.app { /** * Gets the {@link firebase.remoteConfig.RemoteConfig `RemoteConfig`} instance. * - * @webonly + * The Remote Config SDK does not work in a Node.js environment. * * @example * ```javascript @@ -1517,7 +1517,7 @@ declare namespace firebase.app { * Gets the {@link firebase.analytics.Analytics `Analytics`} service for the * current app. If the current app is not the default one, throws an error. * - * @webonly + * The Analytics SDK does not work in a Node.js environment. * * @example * ```javascript @@ -1532,7 +1532,9 @@ declare namespace firebase.app { } /** - * @webonly + * Firebase App Check does not work in a Node.js environment using `ReCaptchaV3Provider` or + * `ReCaptchaEnterpriseProvider`, but can be used in Node.js if you use + * `CustomProvider` and write your own attestation method. */ declare namespace firebase.appCheck { /** @@ -1696,7 +1698,7 @@ declare namespace firebase.appCheck { } /** - * @webonly + * The Installations SDK does not work in a Node.js environment. */ declare namespace firebase.installations { /** @@ -1745,7 +1747,7 @@ declare namespace firebase.installations { } /** - * @webonly + * The Performance SDK does not work in a Node.js environment. */ declare namespace firebase.performance { /** @@ -1868,7 +1870,7 @@ declare namespace firebase.performance { } /** - * @webonly + * The Remote Config SDK does not work in a Node.js environment. */ declare namespace firebase.remoteConfig { /** @@ -2670,7 +2672,7 @@ declare namespace firebase.auth { * Firebase console. * * - * @webonly + * This method does not work in a Node.js environment. * * @example * ```javascript @@ -3350,7 +3352,7 @@ declare namespace firebase.auth { * console. * * - * @webonly + * This method does not work in a Node.js environment. * * @example * ```javascript @@ -3413,7 +3415,7 @@ declare namespace firebase.auth { * console. * * - * @webonly + * This method does not work in a Node.js environment. * * @param provider The provider to authenticate. * The provider has to be an OAuth provider. Non-OAuth providers like {@link @@ -4628,7 +4630,7 @@ declare namespace firebase.auth { * An {@link https://www.google.com/recaptcha/ reCAPTCHA}-based application * verifier. * - * @webonly + * This class does not work in a Node.js environment. * * @param container The reCAPTCHA container parameter. This * has different meaning depending on whether the reCAPTCHA is hidden or @@ -4647,7 +4649,6 @@ declare namespace firebase.auth { */ class RecaptchaVerifier extends RecaptchaVerifier_Instance {} /** - * @webonly * @hidden */ class RecaptchaVerifier_Instance @@ -4776,7 +4777,7 @@ declare namespace firebase.auth { } /** - * @webonly + * The Analytics SDK does not work in a Node.js environment. */ declare namespace firebase.analytics { /** @@ -7436,7 +7437,7 @@ declare namespace firebase.database.ServerValue { } /** - * @webonly + * The Messaging SDK does not work in a Node.js environment. */ declare namespace firebase.messaging { /** @@ -8048,30 +8049,6 @@ declare namespace firebase.storage { UNSUPPORTED_ENVIRONMENT = 'unsupported-environment' } - /** - * An error returned by the Firebase Storage SDK. - */ - export interface FirebaseStorageError extends FirebaseError { - /** - * Stores custom error data unique to the `StorageError`. - */ - customData: { - serverResponse: string | null; - }; - - get status(): number; - set status(status: number); - /** - * Compares a `StorageErrorCode` against this error's code, filtering out the prefix. - */ - _codeEquals(code: StorageErrorCode): boolean; - /** - * Optional response message that was added by the server. - */ - get serverResponse(): null | string; - set serverResponse(serverResponse: string | null); - } - interface StorageObserver { next?: NextFn | null; error?: (error: FirebaseStorageError) => void | null; @@ -8269,6 +8246,30 @@ declare namespace firebase.storage { */ totalBytes: number; } + + /** + * An error returned by the Firebase Storage SDK. + */ + export interface FirebaseStorageError extends FirebaseError { + /** + * Stores custom error data unique to the `StorageError`. + */ + customData: { + serverResponse: string | null; + }; + + get status(): number; + set status(status: number); + /** + * Compares a `StorageErrorCode` against this error's code, filtering out the prefix. + */ + _codeEquals(code: StorageErrorCode): boolean; + /** + * Optional response message that was added by the server. + */ + get serverResponse(): null | string; + set serverResponse(serverResponse: string | null); + } } declare namespace firebase.firestore { @@ -8327,7 +8328,7 @@ declare namespace firebase.firestore { * work around a specific network reliability issue, please tell us about * it in https://github.com/firebase/firebase-js-sdk/issues/1674. * - * @webonly + * This setting does not work in a Node.js environment. */ experimentalForceLongPolling?: boolean; @@ -8339,7 +8340,7 @@ declare namespace firebase.firestore { * This setting will likely be enabled by default in future releases and cannot be * combined with `experimentalForceLongPolling`. * - * @webonly + * This setting does not work in a Node.js environment. */ experimentalAutoDetectLongPolling?: boolean; diff --git a/packages/firestore/src/api/cache_config.ts b/packages/firestore/src/api/cache_config.ts index 57579d096a3..9d50568da83 100644 --- a/packages/firestore/src/api/cache_config.ts +++ b/packages/firestore/src/api/cache_config.ts @@ -248,6 +248,8 @@ export function memoryLocalCache( /** * An settings object to configure an `PersistentLocalCache` instance. + * + * Persistent cache cannot be used in a Node.js environment. */ export type PersistentCacheSettings = { /** @@ -271,6 +273,8 @@ export type PersistentCacheSettings = { /** * Creates an instance of `PersistentLocalCache`. The instance can be set to * `FirestoreSettings.cache` to tell the SDK which cache layer to use. + * + * Persistent cache cannot be used in a Node.js environment. */ export function persistentLocalCache( settings?: PersistentCacheSettings diff --git a/packages/firestore/src/api/database.ts b/packages/firestore/src/api/database.ts index 93aab4880d9..311e665e048 100644 --- a/packages/firestore/src/api/database.ts +++ b/packages/firestore/src/api/database.ts @@ -320,6 +320,8 @@ export function configureFirestore(firestore: Firestore): void { * * unimplemented: The browser is incompatible with the offline * persistence implementation. * + * Persistence cannot be used in a Node.js environment. + * * @param firestore - The {@link Firestore} instance to enable persistence for. * @param persistenceSettings - Optional settings object to configure * persistence. diff --git a/packages/firestore/src/api/settings.ts b/packages/firestore/src/api/settings.ts index 682f2d2d20c..40c0df79fa2 100644 --- a/packages/firestore/src/api/settings.ts +++ b/packages/firestore/src/api/settings.ts @@ -25,6 +25,8 @@ export { DEFAULT_HOST } from '../lite-api/settings'; /** * Settings that can be passed to `enableIndexedDbPersistence()` to configure * Firestore persistence. + * + * Persistence cannot be used in a Node.js environment. */ export interface PersistenceSettings { /** @@ -81,6 +83,8 @@ export interface FirestoreSettings extends LiteSettings { * 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. + * + * This setting cannot be used in a Node.js environment. */ experimentalForceLongPolling?: boolean; @@ -95,6 +99,8 @@ export interface FirestoreSettings extends LiteSettings { * polling is now enabled by default. To disable it, set this setting to * `false`, and please open a GitHub issue to share the problems that * motivated you disabling long-polling auto-detection. + * + * This setting cannot be used in a Node.js environment. */ experimentalAutoDetectLongPolling?: boolean; diff --git a/packages/installations/src/index.ts b/packages/installations/src/index.ts index f67d6c1571b..c16abc2b0b1 100644 --- a/packages/installations/src/index.ts +++ b/packages/installations/src/index.ts @@ -1,5 +1,6 @@ /** - * Firebase Installations + * The Firebase Installations Web SDK. + * This SDK does not work in a Node.js environment. * * @packageDocumentation */ diff --git a/packages/messaging/src/index.ts b/packages/messaging/src/index.ts index 389e45f5ab8..df9056e21b3 100644 --- a/packages/messaging/src/index.ts +++ b/packages/messaging/src/index.ts @@ -1,5 +1,6 @@ /** - * Firebase Cloud Messaging + * The Firebase Cloud Messaging Web SDK. + * This SDK does not work in a Node.js environment. * * @packageDocumentation */ diff --git a/packages/performance/src/index.ts b/packages/performance/src/index.ts index 1896e89132d..4d3713f0614 100644 --- a/packages/performance/src/index.ts +++ b/packages/performance/src/index.ts @@ -1,5 +1,6 @@ /** - * Firebase Performance Monitoring + * The Firebase Performance Monitoring Web SDK. + * This SDK does not work in a Node.js environment. * * @packageDocumentation */ diff --git a/packages/remote-config/src/index.ts b/packages/remote-config/src/index.ts index b51873453fe..288a8ed1827 100644 --- a/packages/remote-config/src/index.ts +++ b/packages/remote-config/src/index.ts @@ -1,5 +1,6 @@ /** - * Firebase Remote Config + * The Firebase Remote Config Web SDK. + * This SDK does not work in a Node.js environment. * * @packageDocumentation */ diff --git a/scripts/docgen-compat/content-sources/js/toc.yaml b/scripts/docgen-compat/content-sources/js/toc.yaml index 1ce2caf8348..2eadbc97038 100644 --- a/scripts/docgen-compat/content-sources/js/toc.yaml +++ b/scripts/docgen-compat/content-sources/js/toc.yaml @@ -282,6 +282,8 @@ toc: path: /docs/reference/js/v8/firebase.storage.SettableMetadata - title: "Storage" path: /docs/reference/js/v8/firebase.storage.Storage + - title: "StorageErrorCode" + path: /docs/reference/js/v8/firebase.storage.StorageErrorCode - title: "StorageObserver" path: /docs/reference/js/v8/firebase.storage.StorageObserver - title: "UploadMetadata" diff --git a/scripts/docgen-compat/content-sources/node/HOME.md b/scripts/docgen-compat/content-sources/node/HOME.md deleted file mode 100644 index 1aa17ec613c..00000000000 --- a/scripts/docgen-compat/content-sources/node/HOME.md +++ /dev/null @@ -1,11 +0,0 @@ -# Firebase JavaScript SDK Reference For Node.js -The Firebase JavaScript SDK implements the client-side libraries used by -applications using Firebase services. This SDK is distributed via: - -- [CDN](/docs/web/setup/#add-sdks-initialize) -- [npm package](https://www.npmjs.com/package/firebase) - -To get started using Firebase, see -[Add Firebase to your JavaScript Project](https://firebase.google.com/docs/web/setup). - -For source code, see the [Firebase JavaScript SDK Github repo](https://github.com/firebase/firebase-js-sdk). diff --git a/scripts/docgen-compat/content-sources/node/toc.yaml b/scripts/docgen-compat/content-sources/node/toc.yaml deleted file mode 100644 index 680604b5778..00000000000 --- a/scripts/docgen-compat/content-sources/node/toc.yaml +++ /dev/null @@ -1,212 +0,0 @@ -toc: -- title: "firebase" - path: /docs/reference/node/firebase - section: - - title: "FirebaseError" - path: /docs/reference/node/firebase.FirebaseError - - title: "FirebaseIdToken" - path: /docs/reference/node/firebase.FirebaseIdToken - -- title: "firebase.app" - path: /docs/reference/node/firebase.app - section: - - title: "App" - path: /docs/reference/node/firebase.app.App - -- title: "firebase.auth" - path: /docs/reference/node/firebase.auth - section: - - title: "Auth" - path: /docs/reference/node/firebase.auth.Auth - - title: "ActionCodeInfo" - path: /docs/reference/node/firebase.auth.ActionCodeInfo - - title: "ActionCodeURL" - path: /docs/reference/node/firebase.auth.ActionCodeURL - - title: "ApplicationVerifier" - path: /docs/reference/node/firebase.auth.ApplicationVerifier - - title: "AuthCredential" - path: /docs/reference/node/firebase.auth.AuthCredential - - title: "AuthError" - path: /docs/reference/node/firebase.auth.AuthError - - title: "AuthProvider" - path: /docs/reference/node/firebase.auth.AuthProvider - - title: "AuthSettings" - path: /docs/reference/node/firebase.auth.AuthSettings - - title: "Config" - path: /docs/reference/node/firebase.auth.Config - - title: "ConfirmationResult" - path: /docs/reference/node/firebase.auth.ConfirmationResult - - title: "EmailAuthProvider" - path: /docs/reference/node/firebase.auth.EmailAuthProvider - - title: "EmulatorConfig" - path: /docs/reference/node/firebase.auth.EmulatorConfig - - title: "Error" - path: /docs/reference/node/firebase.auth.Error - - title: "FacebookAuthProvider" - path: /docs/reference/node/firebase.auth.FacebookAuthProvider - - title: "GithubAuthProvider" - path: /docs/reference/node/firebase.auth.GithubAuthProvider - - title: "GoogleAuthProvider" - path: /docs/reference/node/firebase.auth.GoogleAuthProvider - - title: "IdTokenResult" - path: /docs/reference/node/firebase.auth.IDTokenResult - - title: "MultiFactorAssertion" - path: /docs/reference/node/firebase.auth.multifactorassertion - - title: "MultiFactorError" - path: /docs/reference/node/firebase.auth.multifactorerror - - title: "MultiFactorInfo" - path: /docs/reference/node/firebase.auth.multifactorinfo - - title: "MultiFactorResolver" - path: /docs/reference/node/firebase.auth.multifactorresolver - - title: "MultiFactorSession" - path: /docs/reference/node/firebase.auth.multifactorsession - - title: "PhoneAuthCredential" - path: /docs/reference/node/firebase.auth.phoneauthcredential - - title: "PhoneMultiFactorAssertion" - path: /docs/reference/node/firebase.auth.phonemultifactorassertion - - title: "PhoneMultiFactorEnrollInfoOptions" - path: /docs/reference/node/firebase.auth.phonemultifactorenrollinfooptions - - title: "PhoneMultiFactorGenerator" - path: /docs/reference/node/firebase.auth.phonemultifactorgenerator - - title: "PhoneMultiFactorInfo" - path: /docs/reference/node/firebase.auth.phonemultifactorinfo - - title: "PhoneMultiFactorSignInInfoOptions" - path: /docs/reference/node/firebase.auth.phonemultifactorsignininfooptions - - title: "PhoneSingleFactorInfoOptions" - path: /docs/reference/node/firebase.auth.phonesinglefactorinfooptions - - title: "MultiFactorUser" - path: /docs/reference/node/firebase.user.multifactoruser - - title: "OAuthCredential" - path: /docs/reference/node/firebase.auth.OAuthCredential - - title: "OAuthCredentialOptions" - path: /docs/reference/node/firebase.auth.OAuthCredentialOptions - - title: "OAuthProvider" - path: /docs/reference/node/firebase.auth.OAuthProvider - - title: "PhoneAuthProvider" - path: /docs/reference/node/firebase.auth.PhoneAuthProvider - - title: "SAMLAuthProvider" - path: /docs/reference/node/firebase.auth.SAMLAuthProvider - - title: "TwitterAuthProvider" - path: /docs/reference/node/firebase.auth.TwitterAuthProvider - - title: "User" - path: /docs/reference/node/firebase.User - - title: "UserInfo" - path: /docs/reference/node/firebase.UserInfo - - title: "UserMetadata" - path: /docs/reference/node/firebase.auth.UserMetadata - -- title: "firebase.database" - path: /docs/reference/node/firebase.database - section: - - title: "DataSnapshot" - path: /docs/reference/node/firebase.database.DataSnapshot - - title: "Database" - path: /docs/reference/node/firebase.database.Database - - title: "OnDisconnect" - path: /docs/reference/node/firebase.database.OnDisconnect - - title: "Query" - path: /docs/reference/node/firebase.database.Query - - title: "Reference" - path: /docs/reference/node/firebase.database.Reference - - title: "ServerValue" - path: /docs/reference/node/firebase.database.ServerValue - - title: "ThenableReference" - path: /docs/reference/node/firebase.database.ThenableReference - - title: "TransactionResult" - path: /docs/reference/node/firebase.database.TransactionResult - -- title: "firebase.firestore" - path: /docs/reference/node/firebase.firestore - section: - - title: "Blob" - path: /docs/reference/node/firebase.firestore.Blob - - title: "CollectionReference" - path: /docs/reference/node/firebase.firestore.CollectionReference - - title: "DocumentChange" - path: /docs/reference/node/firebase.firestore.DocumentChange - - title: "DocumentReference" - path: /docs/reference/node/firebase.firestore.DocumentReference - - title: "DocumentSnapshot" - path: /docs/reference/node/firebase.firestore.DocumentSnapshot - - title: "FieldPath" - path: /docs/reference/node/firebase.firestore.FieldPath - - title: "FieldValue" - path: /docs/reference/node/firebase.firestore.FieldValue - - title: "Firestore" - path: /docs/reference/node/firebase.firestore.Firestore - - title: "FirestoreDataConverter" - path: /docs/reference/node/firebase.firestore.FirestoreDataConverter - - title: "FirestoreError" - path: /docs/reference/node/firebase.firestore.FirestoreError - - title: "GeoPoint" - path: /docs/reference/node/firebase.firestore.GeoPoint - - title: "GetOptions" - path: /docs/reference/node/firebase.firestore.GetOptions - - title: "LoadBundleTask" - path: /docs/reference/node/firebase.firestore.LoadBundleTask - - title: "LoadBundleTaskProgress" - path: /docs/reference/node/firebase.firestore.LoadBundleTaskProgress - - title: "PersistenceSettings" - path: /docs/reference/node/firebase.firestore.PersistenceSettings - - title: "Query" - path: /docs/reference/node/firebase.firestore.Query - - title: "QueryDocumentSnapshot" - path: /docs/reference/node/firebase.firestore.QueryDocumentSnapshot - - title: "QuerySnapshot" - path: /docs/reference/node/firebase.firestore.QuerySnapshot - - title: "SetOptions" - path: /docs/reference/node/firebase.firestore.SetOptions - - title: "Settings" - path: /docs/reference/node/firebase.firestore.Settings - - title: "SnapshotListenOptions" - path: /docs/reference/node/firebase.firestore.SnapshotListenOptions - - title: "SnapshotMetadata" - path: /docs/reference/node/firebase.firestore.SnapshotMetadata - - title: "SnapshotOptions" - path: /docs/reference/node/firebase.firestore.SnapshotOptions - - title: "Timestamp" - path: /docs/reference/node/firebase.firestore.Timestamp - - title: "Transaction" - path: /docs/reference/node/firebase.firestore.Transaction - - title: "WriteBatch" - path: /docs/reference/node/firebase.firestore.WriteBatch - -- title: "firebase.functions" - path: /docs/reference/node/firebase.functions - section: - - title: "Functions" - path: /docs/reference/node/firebase.functions.Functions - - title: "HttpsCallable" - path: /docs/reference/node/firebase.functions.HttpsCallable - - title: "HttpsCallableOptions" - path: /docs/reference/node/firebase.functions.HttpsCallableOptions - - title: "HttpsCallableResult" - path: /docs/reference/node/firebase.functions.HttpsCallableResult - - title: "HttpsError" - path: /docs/reference/node/firebase.functions.HttpsError - -- title: "firebase.storage" - path: /docs/reference/node/firebase.storage - section: - - title: "FirebaseStorageError" - path: /docs/reference/node/firebase.storage.FirebaseStorageError - - title: "FullMetadata" - path: /docs/reference/node/firebase.storage.FullMetadata - - title: "ListOptions" - path: /docs/reference/node/firebase.storage.ListOptions - - title: "ListResult" - path: /docs/reference/node/firebase.storage.ListResult - - title: "Reference" - path: /docs/reference/node/firebase.storage.Reference - - title: "SettableMetadata" - path: /docs/reference/node/firebase.storage.SettableMetadata - - title: "Storage" - path: /docs/reference/node/firebase.storage.Storage - - title: "StorageObserver" - path: /docs/reference/node/firebase.storage.StorageObserver - - title: "UploadMetadata" - path: /docs/reference/node/firebase.storage.UploadMetadata - - title: "UploadTask" - path: /docs/reference/node/firebase.storage.UploadTask - - title: "UploadTaskSnapshot" - path: /docs/reference/node/firebase.storage.UploadTaskSnapshot \ No newline at end of file diff --git a/scripts/docgen-compat/generate-docs.js b/scripts/docgen-compat/generate-docs.js index 0aed77640f7..b2054286297 100644 --- a/scripts/docgen-compat/generate-docs.js +++ b/scripts/docgen-compat/generate-docs.js @@ -26,11 +26,6 @@ const repoPath = path.resolve(`${__dirname}/../..`); // Command-line options. const { api: apiType, source: sourceFile } = yargs - .option('api', { - default: 'js', - describe: 'api to generate docs for ("js" or "node")', - type: 'string' - }) .option('source', { default: `${repoPath}/packages/firebase/compat/index.d.ts`, describe: 'Typescript source file(s)', @@ -43,7 +38,6 @@ const destinationDir = apiType === 'js' ? 'js/v8' : apiType; const docPath = path.resolve(`${__dirname}/html/${destinationDir}`); const contentPath = path.resolve(`${__dirname}/content-sources/${apiType}`); const tempHomePath = path.resolve(`${contentPath}/HOME_TEMP.md`); -const tempNodeSourcePath = path.resolve(`${__dirname}/index.node.d.ts`); const devsitePath = `/docs/reference/${destinationDir}/`; /** @@ -61,7 +55,7 @@ function stripPath(path) { * Additional config options come from ./typedoc.js */ function runTypedoc() { - const typeSource = apiType === 'node' ? tempNodeSourcePath : sourceFile; + const typeSource = sourceFile; const command = `${repoPath}/node_modules/.bin/typedoc ${typeSource} \ --tsconfig ${__dirname}/tsconfig.json \ --out ${docPath} \ @@ -108,15 +102,10 @@ function fixLinks(file) { let badLinkCleanup = caseFixedLinks.replace( /{@link (.+)}/g, (all, text) => { - // It's expected to have some broken @link tags in Node docs - // since they could reference some pages only generated for JS. - // Just render as plain text. Warn if it's not a Node doc. - if (!file.includes('/node/')) { - console.log( - `Unable to generate link for "${all} in ${file}", ` + - `removing markup and rendering as plain text.` - ); - } + console.log( + `Unable to generate link for "${all} in ${file}", ` + + `removing markup and rendering as plain text.` + ); return text; } ); @@ -205,12 +194,10 @@ function checkForMissingFilesAndFixFilenameCase() { /** * Gets a list of html files in generated dir and checks if any are not * found in toc.yaml. - * Option to remove the file if not found (used for node docs). * * @param {Array} filenamesFromToc Filenames pulled from toc.yaml - * @param {boolean} shouldRemove Should just remove the file */ -function checkForUnlistedFiles(filenamesFromToc, shouldRemove) { +function checkForUnlistedFiles(filenamesFromToc) { return fs.readdir(docPath).then(files => { const htmlFiles = files .filter(filename => filename.slice(-4) === 'html') @@ -282,8 +269,7 @@ function fixAllLinks(htmlFiles) { } const PROJECT_FILE_PATH = { - 'js': '/docs/reference/js/v8/_project.yaml', - 'node': '/docs/reference/node/_project.yaml' + 'js': '/docs/reference/js/v8/_project.yaml' }; async function setProjectYamlPath(api) { const defaultTemplatePath = path.resolve( @@ -299,55 +285,6 @@ async function setProjectYamlPath(api) { await fs.writeFile(defaultTemplatePath, replacedText); } -/** - * Generate an temporary abridged version of index.d.ts used to create - * Node docs. - */ -async function generateNodeSource() { - const sourceText = await fs.readFile(sourceFile, 'utf8'); - - // Parse index.d.ts. A dummy filename is required but it doesn't create a - // file. - let typescriptSourceFile = typescript.createSourceFile( - 'temp.d.ts', - sourceText, - typescript.ScriptTarget.ES2015, - /*setParentNodes */ false - ); - - /** - * Typescript transformer function. Removes nodes tagged with @webonly. - */ - const removeWebOnlyNodes = context => rootNode => { - function visit(node) { - if ( - node.jsDoc && - node.jsDoc.some( - item => - item.tags && - item.tags.some(tag => tag.tagName.escapedText === 'webonly') - ) - ) { - return null; - } - return typescript.visitEachChild(node, visit, context); - } - return typescript.visitNode(rootNode, visit); - }; - - // Use above transformer on source AST to remove nodes tagged with @webonly. - const result = typescript.transform(typescriptSourceFile, [ - removeWebOnlyNodes - ]); - - // Convert transformed AST to text and write to file. - const printer = typescript.createPrinter(); - return fs.writeFile( - tempNodeSourcePath, - printer.printFile(result.transformed[0]) - ); -} - /** * Main document generation process. * @@ -370,11 +307,6 @@ Promise.all([ tocText = tocRaw; return generateTempHomeMdFile(tocRaw, homeRaw); }) - .then(() => { - if (apiType === 'node') { - return generateNodeSource(); - } - }) .then(() => { setProjectYamlPath(apiType); }) @@ -385,10 +317,6 @@ Promise.all([ console.log(output.stdout); // Clean up temp home markdown file. (Nothing needs to wait for this.) fs.unlink(tempHomePath); - // Clean up temp node index.d.ts file if it exists. - if (await fs.exists(tempNodeSourcePath)) { - fs.unlink(tempNodeSourcePath); - } }) // Write out TOC file. Do this after Typedoc step to prevent Typedoc // erroring when it finds an unexpected file in the target dir. @@ -407,11 +335,8 @@ Promise.all([ // Not blocking. .then(checkForMissingFilesAndFixFilenameCase) // Check for files that exist but aren't listed in the TOC and warn. - // (If API is node, actually remove the file.) // Removal is blocking, warnings aren't. - .then(filenamesFromToc => - checkForUnlistedFiles(filenamesFromToc, apiType === 'node') - ) + .then(filenamesFromToc => checkForUnlistedFiles(filenamesFromToc)) // Write a _toc_autogenerated.yaml to record what files were created. .then(htmlFiles => writeGeneratedFileList(htmlFiles)) // Correct the links in all the generated html files now that files have diff --git a/scripts/docgen-compat/theme/layouts/default.hbs b/scripts/docgen-compat/theme/layouts/default.hbs index d2d327c10b2..8572983d867 100644 --- a/scripts/docgen-compat/theme/layouts/default.hbs +++ b/scripts/docgen-compat/theme/layouts/default.hbs @@ -4,7 +4,7 @@ - +