From 8ce95bf6f8de590f84206ae0c75e39ade458abc3 Mon Sep 17 00:00:00 2001
From: James Daniels <jamesdaniels@google.com>
Date: Fri, 10 Jan 2025 14:32:02 -0500
Subject: [PATCH] Zone docs and switch to warnings (#3608)

* Warn rather than error, thats trippin folk

* Add doc on zone wrappers

* Words
---
 docs/zones.md | 21 +++++++++++++++++++++
 src/zones.ts  |  4 ++--
 2 files changed, 23 insertions(+), 2 deletions(-)
 create mode 100644 docs/zones.md

diff --git a/docs/zones.md b/docs/zones.md
new file mode 100644
index 000000000..2b2e39b82
--- /dev/null
+++ b/docs/zones.md
@@ -0,0 +1,21 @@
+<small>
+<a href="https://github.com/angular/angularfire">AngularFire</a> &#10097; <a href="../README.md#developer-guide">Developer Guide</a> &#10097; Zone Wrappers
+</small>
+
+# Zone Wrappers
+
+AngularFire wraps the [framework agnostic Firebase JS SDK](https://github.com/firebase/firebase-js-sdk) and [RxFire](https://github.com/firebaseextended/rxfire) to ensure proper functionality in Zone and Zoneless applications alike.
+
+These wrappers ensure Firebase APIs are called outside of the Angular zone. This isolates side-effects such as timers so that they do not destabilize your application. 
+
+Observables, Promise-based APIs, and those with callbacks will purposely destabilize your application until a initial value is returned, this ensures that server-side rendering (SSR) and static site generation (SSG/pre-rendering) wait for data before rendering the page's HTML.
+
+## Consequences of not Zone wrapping
+
+When using a Firebase or RxFire API without importing from AngularFire or if AngularFire APIs are used outside of an injection context you _may_ experience instability.
+
+instability can be difficult to track down ([see Resolving zone pollution in the Angular docs](https://angular.dev/best-practices/zone-pollution)). To help with debugging, AngularFire emits warnings when it is unable to Zone wrap an API while in dev-mode. **Often these messages can be safely ignored** but we'd rather be verbose.
+
+When an application is unstable change-detection, two-way binding, and rehydration may not work as expected—leading to both subtle and non-subtle bugs in your application. Further, server-side rendering (SSR) and static site generation (SSG/pre-rendering) may timeout or render a blank page.
+
+There are a number of situations where AngularFire's Zone wrapping is inconsequential such adding/deleting/updating a document in response to user-input, signing a user in, calling a Cloud Function, etc. So long as no long-lived side-effects are kicked off, your application should be ok. Most Promise based APIs are fairly safe without zone wrapping. 
diff --git a/src/zones.ts b/src/zones.ts
index d8505433e..1f845322a 100644
--- a/src/zones.ts
+++ b/src/zones.ts
@@ -81,11 +81,11 @@ function getSchedulers() {
 var alreadyWarned = false;
 function warnOutsideInjectionContext(original: any, operation: string) {
   if (isDevMode()) {
-    console.warn(`Firebase API called outside injection context: ${operation}(${original.name})`);
     if (!alreadyWarned) {
       alreadyWarned = true;
-      console.error("Calling Firebase APIs outside of an Injection context may destabilize your application leading to subtle change-detection and hydration bugs. Find more at https://github.com/angular/angularfire/blob/main/docs/zones.md");
+      console.warn("Calling Firebase APIs outside of an Injection context may destabilize your application leading to subtle change-detection and hydration bugs. Find more at https://github.com/angular/angularfire/blob/main/docs/zones.md");
     }
+    console.warn(`Firebase API called outside injection context: ${operation}(${original.name})`);
   }
 }