build: classify the firebase symbols a version raise would newly wrap (#3759)

The build regenerates src/<module>/firebase.ts from the declarations of whatever
firebase is installed, wrapping every lowercase-initial function. Raising the
minimum version would wrap symbols nobody has classified, and one breaks: the auth
persistence exports are classes that firebase constructs with `new`, and the
wrapper replaces them with an ordinary function. These entries settle that first
and stay inert until the version rises.

Do not wrap maximum, minimum, getTemplateGenerativeModel, makeMemoryCacheProvider
or browserCookiePersistence. Wrap the messaging subscriptions with blockUntilFirst
off, matching onMessage, since they fire on a registration change that may never
happen and would otherwise hold a pending task open indefinitely.

The generator is now exported so `npm run generate` runs it without `ng build`,
and it fails on an override key its entry point does not declare, which is
otherwise ignored in silence.

Also removes ngPostUpdate, an ng update migration that returned its Tree unchanged,
and adds a docs/zones.md section on what a call outside an injection context loses.

Refs #3756

Author: armando-navarro

docs/zones.md

@@ -49,6 +49,19 @@ readonly refreshed$ = this.refresh$.pipe(switchMap(() => this.items$));
 
 Reach for `runInInjectionContext` only when the call genuinely must run inside the callback, as the per-user query above does (it needs the signed-in user's `uid`).
 
+### Why the injection context is required
+
+AngularFire cannot create an injection context, only borrow the one you are already in.
+
+When you call a wrapped API, the first thing AngularFire does is ask Angular for three things with `inject()`: its own scheduler service, Angular's `PendingTasks` register, and an `EnvironmentInjector`. `inject()` only works inside an injection context, so outside of one the first of them throws and the rest are never reached. AngularFire catches that, warns while in dev-mode as described under Logging below, and calls the Firebase API directly with nothing added.
+
+That division is worth knowing, because it explains what you are and are not responsible for:
+
+* **You** supply the context at the call site, from a field initializer, a constructor, or an explicit `runInInjectionContext`.
+* **AngularFire** re-enters the environment injector inside a callback you hand to the call itself, which is why you never wrap an `onSnapshot` handler yourself. That reaches anything provided at the application level, but not providers declared on a component, and it does not extend to subscribers of a returned Observable, which is what the `switchMap` and `runInInjectionContext` example above is for.
+
+What you lose depends on the call. A call that does asynchronous work, such as `onSnapshot`, `getDoc` or `collectionData`, is normally added to Angular's `PendingTasks` register, which is what server-side rendering waits on before it serializes the page. Called outside a context, it never is. A call that returns immediately, such as `getFirestore`, was never registered anyway, so it loses only the zone handling.
+
 ## Logging
 
 You may see a log warning, `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` when developing your application.

package.json

@@ -23,6 +23,7 @@
     "test:build": "bash ./test/ng-build/build.sh",
     "test:all": "npm run test:node-esm && npm run test:chrome-headless && npm run test:typings && npm run test:build",
     "build": "rimraf dist && tspc -p tsconfig.build.json && node --trace-warnings ./tools/build.js && npm pack ./dist/packages-dist",
+    "generate": "tspc -p tsconfig.build.json && node -e \"require('./tools/build.js').zoneWrapExports().catch(err => { console.error(err); process.exit(1); })\"",
     "buildd": "tsc -p tsconfig.build.json && node --trace-warnings ./tools/build.js && npm pack ./dist/packages-dist",
     "build:jasmine": "npx tsc -p tsconfig.jasmine.json --module es2015 && cp ./dist/out-tsc/jasmine/tools/jasmine.js ./dist/out-tsc/jasmine/tools/jasmine.mjs && npx tsc -p tsconfig.jasmine.json && cp ./dist/packages-dist/schematics/versions.json ./dist/out-tsc/jasmine/src/schematics",
     "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 1"

src/schematics/migration.json

@@ -10,11 +10,6 @@
             "version": "21.0.0",
             "description": "Align the workspace's firebase dependency with the range @angular/fire 21 requires, and rewrite Vertex AI imports to Firebase AI Logic (getVertexAI callers keep the Vertex AI backend)",
             "factory": "./update/v21#ngUpdate"
-        },
-        "ng-post-upgate": {
-            "description": "Print out results after ng-update",
-            "factory": "./update#ngPostUpdate",
-            "private": true
         }
     }
 }

src/schematics/tsconfig.json

@@ -22,7 +22,6 @@
         "outDir": "../../dist/packages-dist/schematics"
     },
     "files": [
-        "update/index.ts",
         "deploy/actions.ts",
         "deploy/builder.ts",
         "add/index.ts",

src/schematics/update/index.ts

@@ -37,9 +37,13 @@ const firestoreOverrides = {
   increment: { logLevel: LogLevel.VERBOSE },
   limit: { logLevel: LogLevel.VERBOSE },
   limitToLast: { logLevel: LogLevel.VERBOSE },
+  // maximum and minimum take no callback and return no promise; wrapping would not benefit them.
+  maximum: null,
   memoryEagerGarbageCollector: null,
   memoryLocalCache: null,
   memoryLruGarbageCollector: null,
+  // See maximum above.
+  minimum: null,
   namedQuery: { logLevel: LogLevel.VERBOSE },
   or: { logLevel: LogLevel.VERBOSE },
   orderBy: { logLevel: LogLevel.VERBOSE },
@@ -61,14 +65,38 @@ const firestoreOverrides = {
   writeBatch: { logLevel: LogLevel.VERBOSE },
 };
 
+/* Override keys firebase's type declarations may not carry, which the generator would otherwise
+ * read as typos. A name lands here because a later release adds it, firebase has removed it, or
+ * firebase keeps it out of its public types on purpose (browserCookiePersistence). Listing a
+ * declared name is harmless: getImagenModel is here for the version this build is heading to.
+ * Keyed by entry point, so a name allowed for one module is not allowed for the rest.
+ * At a version bump, drop a name from here but KEEP its override entry. */
+const overridesFirebaseDoesNotDeclare: Record<string, string[]> = {
+  'firebase/ai': ['getImagenModel', 'getTemplateGenerativeModel'],
+  'firebase/auth': ['browserCookiePersistence'],
+  'firebase/data-connect': ['makeMemoryCacheProvider'],
+  'firebase/firestore': ['maximum', 'minimum'],
+  'firebase/messaging': ['onRegistered', 'onUnregistered', 'unregister'],
+};
+
+type Overrides = Record<string, OverrideOptions | null>;
+
 function zoneWrapExports() {
+  /* One overrides object can be applied to several entry points, so the keys it may legally name
+   * are the union of their export lists. firestoreOverrides covers both firestore and
+   * firestore/lite, and only firestore has persistentLocalCache and the rest. */
+  const exportsSeenPerOverrides = new Map<Overrides, Set<string>>();
   const reexport = async (
     module: string,
     name: string,
     path: string,
     exports: string[],
-    overrides: Record<string, OverrideOptions | null> = {}
+    overrides: Overrides = {}
   ) => {
+    const seen = exportsSeenPerOverrides.get(overrides) ?? new Set<string>();
+    exports.forEach(exportName => seen.add(exportName));
+    (overridesFirebaseDoesNotDeclare[path] ?? []).forEach(undeclared => seen.add(undeclared));
+    exportsSeenPerOverrides.set(overrides, seen);
     const imported = await import(path);
     const toBeExported: [string, string, boolean][] = exports.sort().
       filter(it => !it.startsWith('_') && overrides[it] !== null && overrides[it]?.override !== true).
@@ -113,12 +141,23 @@ ${exportedZoneWrappedFns}
 `;
     await writeFile(filePath, fileOutput);
   };
+  const failOnUnrecognizedOverrides = () => {
+    const unrecognized = [...exportsSeenPerOverrides].flatMap(([overrides, seen]) =>
+      Object.keys(overrides).filter(key => !seen.has(key) && overrides[key]?.override !== true));
+    if (unrecognized.length) {
+      throw new Error(
+        `Override keys their entry point does not declare: ${unrecognized.join(', ')}. ` +
+        'Overrides are matched by name, so this one is silently ignored and the symbol keeps the ' +
+        'default. Fix the spelling, move it to the right block, or add it to ' +
+        'overridesFirebaseDoesNotDeclare.'
+      );
+    }
+  };
   return Promise.all([
     reexport('ai', 'firebase', 'firebase/ai', tsKeys<typeof import('firebase/ai')>(), {
-      // Removed in @firebase/ai 2.15.0 (firebase 12.18.0), which the ^12.4.0 range
-      // resolves for fresh installs. A named import here would make consumer builds
-      // fail on that version, so only re-export it through the star export, which
-      // tracks whichever firebase is installed.
+      // Unwrapped via the star export: no callback, returns the model object directly.
+      getTemplateGenerativeModel: null,
+      // Removed in @firebase/ai 2.15.0 (firebase 12.18.0).
       getImagenModel: null,
     }),
     reexport('analytics', 'firebase', 'firebase/analytics', tsKeys<typeof import('firebase/analytics')>(), {
@@ -138,7 +177,11 @@ ${exportedZoneWrappedFns}
     reexport('auth', 'rxfire', 'rxfire/auth', tsKeys<typeof import('rxfire/auth')>()),
     reexport('auth', 'firebase', 'firebase/auth', tsKeys<typeof import('firebase/auth')>(), {
       debugErrorMap: null,
+      /* These 5 persistence entries MUST stay unwrapped. Though their type declarations
+       * disagree, they are classes, and wrapping would replace them with ordinary functions
+       * that throw when used with `new`. */
       inMemoryPersistence: null,
+      browserCookiePersistence: null,
       browserLocalPersistence: null,
       browserSessionPersistence: null,
       indexedDBLocalPersistence: null,
@@ -209,6 +252,8 @@ ${exportedZoneWrappedFns}
       update: { logLevel: LogLevel.VERBOSE },
     }),
     reexport('data-connect', 'firebase', 'firebase/data-connect', tsKeys<typeof import('firebase/data-connect')>(), {
+      // Unwrapped via the star export: no callback, returns a plain settings value.
+      makeMemoryCacheProvider: null,
       mutationRef: { logLevel: LogLevel.VERBOSE },
       queryRef: { logLevel: LogLevel.VERBOSE },
       toQueryRef: { logLevel: LogLevel.VERBOSE },
@@ -225,10 +270,14 @@ ${exportedZoneWrappedFns}
     reexport('messaging', 'firebase', 'firebase/messaging', tsKeys<typeof import('firebase/messaging')>(), {
       isSupported: { blockUntilFirst: false },
       onMessage: { blockUntilFirst: false },
+      // `blockUntilFirst: false` otherwise `ApplicationRef.isStable` may never become `true`.
+      onRegistered: { blockUntilFirst: false },
+      onUnregistered: { blockUntilFirst: false },
       deleteToken: { logLevel: LogLevel.VERBOSE },
+      // Quiets the per-call log line, matching deleteToken above.
+      unregister: { logLevel: LogLevel.VERBOSE },
     }),
     reexport('remote-config', 'rxfire', 'rxfire/remote-config', tsKeys<typeof import('rxfire/remote-config')>(), {
-      isSupported: { blockUntilFirst: false },
       getValue: { exportName: 'getValueChanges' },
       getString: { exportName: 'getStringChanges' },
       getNumber: { exportName: 'getNumberChanges' },
@@ -259,7 +308,7 @@ ${exportedZoneWrappedFns}
       collection: { exportName: 'collectionSnapshots' },
     }),
     reexport('firestore/lite', 'firebase', 'firebase/firestore/lite', tsKeys<typeof import('firebase/firestore/lite')>(), firestoreOverrides),
-  ]);
+  ]).then(failOnUnrecognizedOverrides);
 }
 
 const src = (...args: string[]) => join(process.cwd(), 'src', ...args);
@@ -331,7 +380,6 @@ function spawnPromise(command: string, args: string[]) {
 // Path segments of each schematic entry point, relative to `schematics/` and without the file
 // extension: esbuild compiles the `.ts` and loadCompiledSchematics requires the emitted `.js`.
 const schematicEntryPoints = [
-  ['update', 'index'],
   ['deploy', 'actions'],
   ['deploy', 'builder'],
   ['add', 'index'],
@@ -409,7 +457,12 @@ async function buildLibrary() {
   ]);
 }
 
-buildLibrary().catch(err => {
-  console.error(err);
-  process.exit(1);
-})
+// Exported so `npm run generate` can run the code generation on its own.
+export { zoneWrapExports };
+
+if (require.main === module) {
+  buildLibrary().catch(err => {
+    console.error(err);
+    process.exit(1);
+  });
+}