refactor(installations)!: migrate to TypeScript

BREAKING CHANGE: installations modular types now match firebase-js-sdk

Please see https://rnfirebase.io/migrating-to-v25 for help migrating if needed.

react-native-firebase has a goal to be a drop-in replacement for firebase-js-sdk, with native extensions and performance. It has always worked that way at the javascript level but the typescript types have been divergent.

We are fixing that as we refactor to typescript. Please bear with us as we get closer to our goal of react-native-firebase matching firebase-js-sdk both in functionality where possible, but also in exact typescript typing.

Specifics for Installations:

changed modular getInstallations() to return the firebase-js-sdk-style Installations type, which only exposes app; TypeScript consumers should use the modular helpers getId(installations), getToken(installations), and deleteInstallations(installations) instead of calling .getId(), .getToken(), or .delete() on the returned instance.
changed modular deleteInstallations(installations) so the installations argument is required in the TypeScript surface, matching firebase-js-sdk. Code that previously relied on the old optional typing should pass getInstallations() explicitly.
preserved the namespaced API surface: installations(), firebase.installations(), firebase.app().installations(), and FirebaseInstallationsTypes.Module remain available for compatibility, with deprecation annotations added.
added explicit modular public types including Installations, IdChangeCallbackFn, and IdChangeUnsubscribeFn.

Author: russellwheatley

.github/scripts/compare-types/configs/installations.ts

@@ -0,0 +1,19 @@
+/**
+ * Known differences between the firebase-js-sdk @firebase/installations public
+ * API and the @react-native-firebase/installations modular API.
+ *
+ * Each entry must have a `name` (the export name) and a `reason` explaining
+ * why the difference exists. Any difference NOT listed here will cause CI to
+ * fail so that new drift is caught and deliberately acknowledged.
+ */
+
+import type { PackageConfig } from '../src/types';
+
+const config: PackageConfig = {
+  nameMapping: {},
+  missingInRN: [],
+  extraInRN: [],
+  differentShape: [],
+};
+
+export default config;

.github/scripts/compare-types/src/registry.ts

@@ -18,6 +18,7 @@ import appCheckConfig from '../configs/app-check';
 import firestoreConfig from '../configs/firestore';
 import firestorePipelinesConfig from '../configs/firestore-pipelines';
 import remoteConfigConfig from '../configs/remote-config';
+import installationsConfig from '../configs/installations';
 import perfConfig from '../configs/perf-config';
 
 const SCRIPT_DIR = path.resolve(__dirname, '..');
@@ -197,6 +198,18 @@ export const packages: PackageEntry[] = [
     ],
     config: appCheckConfig,
   },
+  {
+    name: 'installations',
+    firebaseSdkTypesPaths: [
+      requiredFirebaseTypes('installations'),
+    ],
+    rnFirebaseModularFiles: [
+      path.join(rnDist('installations'), 'types', 'installations.d.ts'),
+      path.join(rnDist('installations'), 'modular.d.ts'),
+    ],
+    rnFirebaseSupportFiles: [path.join(rnDist('installations'), 'types', 'internal.d.ts')],
+    config: installationsConfig,
+  },
   {
     name: 'firestore',
     firebaseSdkTypesPaths: [requiredFirebaseTypes('firestore')],

packages/installations/__tests__/installations.test.ts

@@ -109,6 +109,7 @@ describe('installations()', function () {
       const installations = getInstallations();
       installationsV9Deprecation(
         () => deleteInstallations(installations),
+        // @ts-expect-error Combines modular and namespace API
         () => installations.delete(),
         'delete',
       );
@@ -118,6 +119,7 @@ describe('installations()', function () {
       const installations = getInstallations();
       installationsV9Deprecation(
         () => getId(installations),
+        // @ts-expect-error Combines modular and namespace API
         () => installations.getId(),
         'getId',
       );
@@ -127,6 +129,7 @@ describe('installations()', function () {
       const installations = getInstallations();
       installationsV9Deprecation(
         () => getToken(installations),
+        // @ts-expect-error Combines modular and namespace API
         () => installations.getToken(),
         'getToken',
       );

packages/installations/lib/index.d.ts

@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2016-present Invertase Limited & Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this library except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+// Export modular/public types.
+export type * from './types/installations';
+
+// Export modular API functions.
+export * from './modular';
+
+// Export namespaced API.
+export type { FirebaseInstallationsTypes } from './types/namespaced';
+export * from './namespaced';
+export { default } from './namespaced';

packages/installations/lib/index.ts

@@ -0,0 +1,80 @@
+/*
+ * Copyright (c) 2016-present Invertase Limited & Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this library except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+import { getApp } from '@react-native-firebase/app';
+import type { FirebaseApp } from '@react-native-firebase/app';
+import { MODULAR_DEPRECATION_ARG } from '@react-native-firebase/app/dist/module/common';
+import type {
+  IdChangeCallbackFn,
+  IdChangeUnsubscribeFn,
+  Installations,
+} from './types/installations';
+import type { InstallationsInternal } from './types/internal';
+
+function withModularDeprecationArg(installations: Installations): InstallationsInternal {
+  return installations as InstallationsInternal;
+}
+
+/**
+ * Returns an instance of Installations associated with the given FirebaseApp instance.
+ */
+export function getInstallations(app?: FirebaseApp): Installations {
+  if (app) {
+    return getApp(app.name).installations();
+  }
+  return getApp().installations();
+}
+
+/**
+ * Deletes the Firebase Installation and all associated data.
+ */
+export function deleteInstallations(installations: Installations): Promise<void> {
+  const internalInstallations = withModularDeprecationArg(installations);
+  return internalInstallations.delete.call(internalInstallations, MODULAR_DEPRECATION_ARG);
+}
+
+/**
+ * Creates a Firebase Installation if there isn't one for the app and returns the Installation ID.
+ */
+export function getId(installations: Installations): Promise<string> {
+  const internalInstallations = withModularDeprecationArg(installations);
+  return internalInstallations.getId.call(internalInstallations, MODULAR_DEPRECATION_ARG);
+}
+
+/**
+ * Returns a Firebase Installations auth token, identifying the current Firebase Installation.
+ */
+export function getToken(installations: Installations, forceRefresh?: boolean): Promise<string> {
+  const internalInstallations = withModularDeprecationArg(installations);
+  return internalInstallations.getToken.call(
+    internalInstallations,
+    forceRefresh,
+    MODULAR_DEPRECATION_ARG,
+  );
+}
+
+/**
+ * Throw an error since react-native-firebase does not support this method.
+ *
+ * Sets a new callback that will get called when Installation ID changes. Returns an unsubscribe function that will remove the callback when called.
+ */
+export function onIdChange(
+  _installations: Installations,
+  _callback: IdChangeCallbackFn,
+): IdChangeUnsubscribeFn {
+  throw new Error('onIdChange() is unsupported by the React Native Firebase SDK.');
+}