refactor(firestore): standalone googleapis_firestore package and multi-db support for firestore (#121)

* docs: update documentation link for sending messages to topic conditions

* refactor: update constructors to use internal factory methods for AppCheck, Auth, Firestore, Messaging, and SecurityRules

* update README

* wip refactor google_cloud_firestore into its own package

* wip refactor google_cloud_firestore files to streamline package structure

* refactor: rename files and update imports for googleapis_firestore package

* docs: add googleapis_firestore package documentation section to index.html

* feat: add multi-database support to Firestore

This change refactors the Firestore integration to support multiple databases within a single `FirebaseApp`, similar to the Node.js Admin SDK.

Key changes:
- `app.firestore()` now accepts an optional `databaseId` to get or create a named database instance.
- Database instances are cached per `databaseId` to ensure the same instance is returned on subsequent calls.
- The `Firestore` service wrapper now manages multiple `googleapis_firestore.Firestore` delegates, one for each database ID.
- Settings are now passed during initialization via `app.firestore(settings: ...)`, and re-initialization with different settings is prevented.
- Added comprehensive unit and integration tests for multi-database functionality, CRUD operations, and emulator support.
- Refactored `EmulatorClient` into the `googleapis_firestore` package and removed redundant exception handling code.

* docs: update README.md with Firestore usage examples and corrections

* chore: fix lint errors

* feat: enhance Firestore example with multi-database support and usage scenarios

* feat: add googleapis_firestore dependency to pubspec.yaml

* feat: add failedPrecondition error code and update error messages in Firestore

* chore: comment out local Firestore emulator configuration in coverage script

* refactor(firestore): simplify and improve firestore tests

Author: demolaf

all_lint_rules.yaml

@@ -219,5 +219,4 @@ linter:
     - use_string_in_part_of_directives
     - use_super_parameters
     - use_test_throws_matchers
-    - use_to_and_as_if_applicable
     - void_checks

doc/index.html

@@ -60,6 +60,12 @@ <h2>dart_firebase_admin</h2>
             <a href="api/dart_firebase_admin/index.html">View Documentation →</a>
         </li>
 
+        <li class="package-item">
+            <h2>googleapis_firestore</h2>
+            <p>Standalone Cloud Firestore client library for Dart. Provides direct access to Firestore database operations including documents, collections, queries, transactions, and batch writes.</p>
+            <a href="api/googleapis_firestore/index.html">View Documentation →</a>
+        </li>
+
         <li class="package-item">
             <h2>googleapis_auth_utils</h2>
             <p>Google APIs authentication utilities used by the Firebase Admin SDK.</p>

packages/dart_firebase_admin/README.md

@@ -114,18 +114,21 @@ print("Token: ${result.token}");
 ### Firestore
 
 ```dart
+import 'package:dart_firebase_admin/dart_firebase_admin.dart';
+import 'package:googleapis_firestore/googleapis_firestore.dart';
+
 final app = FirebaseApp.initializeApp();
 
 // Getting a document
 final snapshot = await app.firestore().collection("users").doc("<user-id>").get();
 print(snapshot.data());
 
 // Querying a collection
-final snapshot = await app.firestore().collection("users")
-  .where('age', .greaterThan, 18)
+final querySnapshot = await app.firestore().collection("users")
+  .where('age', WhereFilter.greaterThan, 18)
   .orderBy('age', descending: true)
   .get();
-print(snapshot.docs())
+print(querySnapshot.docs);
 
 // Running a transaction (e.g. adding credits to a balance)
 final balance = await app.firestore().runTransaction((tsx) async {
@@ -136,13 +139,13 @@ final balance = await app.firestore().runTransaction((tsx) async {
   final snapshot = await tsx.get(ref);
 
   // Get the users current balance (or 0 if it doesn't exist)
-  final currentBalance = snapshot.exists() ? snapshot.data()?['balanace'] ?? 0 : 0;
+  final currentBalance = snapshot.exists ? snapshot.data()?['balance'] ?? 0 : 0;
 
   // Add 10 credits to the users balance
   final newBalance = currentBalance + 10;
 
   // Update the document within the transaction
-  await tsx.update(ref, {
+  tsx.update(ref, {
     'balance': newBalance,
   });
 

packages/dart_firebase_admin/example/lib/main.dart

@@ -10,7 +10,7 @@ Future<void> main() async {
   // await authExample(admin);
 
   // Uncomment to run firestore example
-  // await firestoreExample(admin);
+  await firestoreExample(admin);
 
   // Uncomment to run project config example
   // await projectConfigExample(admin);
@@ -61,6 +61,8 @@ Future<void> authExample(FirebaseApp admin) async {
 Future<void> firestoreExample(FirebaseApp admin) async {
   print('\n### Firestore Example ###\n');
 
+  // Example 1: Using the default database
+  print('> Using default database...\n');
   final firestore = admin.firestore();
 
   try {
@@ -73,6 +75,49 @@ Future<void> firestoreExample(FirebaseApp admin) async {
   } catch (e) {
     print('> Error setting document: $e');
   }
+
+  // Example 2: Using a named database (multi-database support)
+  print('\n> Using named database "my-database"...\n');
+  final namedFirestore = admin.firestore(databaseId: 'my-database');
+
+  try {
+    final collection = namedFirestore.collection('products');
+    await collection.doc('product-1').set({
+      'name': 'Widget',
+      'price': 19.99,
+      'inStock': true,
+    });
+    print('> Document written to named database\n');
+
+    final doc = await collection.doc('product-1').get();
+    if (doc.exists) {
+      print('> Retrieved from named database: ${doc.data()}');
+    }
+  } catch (e) {
+    print('> Error with named database: $e');
+  }
+
+  // Example 3: Using multiple databases simultaneously
+  print('\n> Demonstrating multiple database access...\n');
+  try {
+    final defaultDb = admin.firestore();
+    final analyticsDb = admin.firestore(databaseId: 'analytics-db');
+
+    await defaultDb.collection('users').doc('user-1').set({
+      'name': 'Alice',
+      'email': 'alice@example.com',
+    });
+
+    await analyticsDb.collection('events').doc('event-1').set({
+      'type': 'page_view',
+      'timestamp': DateTime.now().toIso8601String(),
+      'userId': 'user-1',
+    });
+
+    print('> Successfully wrote to multiple databases');
+  } catch (e) {
+    print('> Error with multiple databases: $e');
+  }
 }
 
 // ignore: unreachable_from_main

packages/dart_firebase_admin/example/pubspec.yaml

@@ -7,3 +7,4 @@ environment:
 
 dependencies:
   dart_firebase_admin: any
+  googleapis_firestore: any

packages/dart_firebase_admin/lib/firestore.dart

@@ -1,6 +1 @@
-export 'src/google_cloud_firestore/firestore.dart'
-    hide
-        $SettingsCopyWith,
-        ApiMapValue,
-        AggregateFieldInternal,
-        FirestoreHttpClient;
+export 'src/firestore/firestore.dart';

packages/dart_firebase_admin/lib/src/app.dart

@@ -6,11 +6,12 @@ import 'dart:io';
 import 'dart:typed_data';
 
 import 'package:equatable/equatable.dart';
-// import 'package:googleapis/cloudfunctions/v2.dart' as auth4;
 import 'package:googleapis/identitytoolkit/v3.dart' as auth3;
 import 'package:googleapis_auth/auth_io.dart' as googleapis_auth;
 import 'package:googleapis_auth_utils/googleapis_auth_utils.dart'
     as googleapis_auth_utils;
+import 'package:googleapis_firestore/googleapis_firestore.dart'
+    as googleapis_firestore;
 import 'package:http/http.dart';
 import 'package:meta/meta.dart';
 

packages/dart_firebase_admin/lib/src/app/app_exception.dart

@@ -70,6 +70,12 @@ enum AppErrorCode {
   /// No Firebase app exists with the given name.
   noApp(code: 'no-app', message: 'No Firebase app exists with the given name.'),
 
+  /// Operation failed because a precondition was not met.
+  failedPrecondition(
+    code: 'failed-precondition',
+    message: 'The operation failed because a precondition was not met.',
+  ),
+
   /// Unable to parse the server response.
   unableToParseResponse(
     code: 'unable-to-parse-response',

packages/dart_firebase_admin/lib/src/app/emulator_client.dart

@@ -26,7 +26,7 @@ class _RequestImpl extends BaseRequest {
 /// Firebase emulators expect this specific bearer token to grant full
 /// admin privileges for local development and testing.
 @internal
-class EmulatorClient implements googleapis_auth.AuthClient {
+class EmulatorClient extends BaseClient implements googleapis_auth.AuthClient {
   EmulatorClient(this.client);
 
   final Client client;
@@ -49,57 +49,7 @@ class EmulatorClient implements googleapis_auth.AuthClient {
   }
 
   @override
-  void close() {
-    client.close();
-  }
-
-  @override
-  Future<Response> head(Uri url, {Map<String, String>? headers}) =>
-      client.head(url, headers: headers);
-
-  @override
-  Future<Response> get(Uri url, {Map<String, String>? headers}) =>
-      client.get(url, headers: headers);
-
-  @override
-  Future<Response> post(
-    Uri url, {
-    Map<String, String>? headers,
-    Object? body,
-    Encoding? encoding,
-  }) => client.post(url, headers: headers, body: body, encoding: encoding);
-
-  @override
-  Future<Response> put(
-    Uri url, {
-    Map<String, String>? headers,
-    Object? body,
-    Encoding? encoding,
-  }) => client.put(url, headers: headers, body: body, encoding: encoding);
-
-  @override
-  Future<Response> patch(
-    Uri url, {
-    Map<String, String>? headers,
-    Object? body,
-    Encoding? encoding,
-  }) => client.patch(url, headers: headers, body: body, encoding: encoding);
-
-  @override
-  Future<Response> delete(
-    Uri url, {
-    Map<String, String>? headers,
-    Object? body,
-    Encoding? encoding,
-  }) => client.delete(url, headers: headers, body: body, encoding: encoding);
-
-  @override
-  Future<String> read(Uri url, {Map<String, String>? headers}) =>
-      client.read(url, headers: headers);
-
-  @override
-  Future<Uint8List> readBytes(Uri url, {Map<String, String>? headers}) =>
-      client.readBytes(url, headers: headers);
+  void close() => client.close();
 }
 
 /// HTTP client for Cloud Tasks emulator that rewrites URLs.

packages/dart_firebase_admin/lib/src/app/firebase_app.dart

@@ -151,42 +151,46 @@ class FirebaseApp {
   /// Gets the App Check service instance for this app.
   ///
   /// Returns a cached instance if one exists, otherwise creates a new one.
-  AppCheck appCheck() =>
-      getOrInitService(FirebaseServiceType.appCheck.name, AppCheck.internal);
+  AppCheck appCheck() => AppCheck.internal(this);
 
   /// Gets the Auth service instance for this app.
   ///
   /// Returns a cached instance if one exists, otherwise creates a new one.
-  Auth auth() => getOrInitService(FirebaseServiceType.auth.name, Auth.internal);
+  Auth auth() => Auth.internal(this);
 
   /// Gets the Firestore service instance for this app.
   ///
   /// Returns a cached instance if one exists, otherwise creates a new one.
   /// Optional [settings] are only applied when creating a new instance.
-  Firestore firestore({Settings? settings}) => getOrInitService(
-    FirebaseServiceType.firestore.name,
-    (app) => Firestore.internal(app, settings: settings),
-  );
+  ///
+  /// For multi-database support, use [databaseId] to specify a named database.
+  /// Default is '(default)'.
+  googleapis_firestore.Firestore firestore({
+    googleapis_firestore.Settings? settings,
+    String databaseId = kDefaultDatabaseId,
+  }) {
+    final service = Firestore.internal(this);
+
+    if (settings != null) {
+      return service.initializeDatabase(databaseId, settings);
+    }
+    return service.getDatabase(databaseId);
+  }
 
   /// Gets the Messaging service instance for this app.
   ///
   /// Returns a cached instance if one exists, otherwise creates a new one.
-  Messaging messaging() =>
-      getOrInitService(FirebaseServiceType.messaging.name, Messaging.internal);
+  Messaging messaging() => Messaging.internal(this);
 
   /// Gets the Security Rules service instance for this app.
   ///
   /// Returns a cached instance if one exists, otherwise creates a new one.
-  SecurityRules securityRules() => getOrInitService(
-    FirebaseServiceType.securityRules.name,
-    SecurityRules.internal,
-  );
+  SecurityRules securityRules() => SecurityRules.internal(this);
 
   /// Gets the Functions service instance for this app.
   ///
   /// Returns a cached instance if one exists, otherwise creates a new one.
-  Functions functions() =>
-      getOrInitService(FirebaseServiceType.functions.name, Functions.internal);
+  Functions functions() => Functions.internal(this);
 
   /// Closes this app and cleans up all associated resources.
   ///