firebase_admin_interop 2.1.0

  • Readme
  • Changelog
  • Example
  • Installing
  • 78

Build Status

Write server-side Firebase applications in Dart using Node.js as a runtime.

Firestore Timestamps migration: #

Firestore deprecated usage of DateTime objects in favor of custom Timestamp type and recommends migrating as soon as possible. By default all timestamps are still returned as DateTime objects and you can access them with DocumentData.getDateTime or DocumentData.setDateTime. To start using Timestamps you must configure Firestore as follows:

final app = FirebaseAdmin.instance.initializeApp();
final firestore = app.firestore();
// Call Firestore.settings at the very beginning before any other calls:
firestore.settings(FirestoreSettings(timestampsInSnapshots: true));
// You can read and write data now, but make sure to use new `setTimestamp` and `getTimestamp`
// methods of `DocumentData`.

Installation #

  1. Add this package as a dependency to your pubspec.yaml:
  firebase_admin_interop: [latest_version]

Run pub get.

  1. Create package.json file to install Node.js modules used by this library:
  "dependencies": {
    "firebase-admin": "8.5.0",
    "@google-cloud/firestore": "2.0.0"

Run npm install.

Usage #

Below is a simple example of using Realtime Database client:

import 'dart:async';
import 'package:firebase_admin_interop/firebase_admin_interop.dart';

Future<void> main() async {
  final serviceAccountKeyFilename = '/absolute/path/to/service-account.json';
  final admin = FirebaseAdmin.instance;
  final cert = admin.certFromPath(serviceAccountKeyFilename);
  final app = admin.initializeApp(new AppOptions(
    credential: cert,
    databaseURL: "YOUR_DB_URL",
  final ref = app.database().ref('/test-path');
  // Write value to the database at "/test-path" location.
  await ref.setValue("Hello world");
  // Read value from the same database location.
  var snapshot = await ref.once("value");
  print(snapshot.val()); // prints "Hello world".

Note that it is only possible to use JSON-compatible values when reading and writing data to the Realtime Database. This includes all primitive types (int, double, bool), string values (String) as well as any List or Map instance.

For Firestore there are a few more supported data types, like DateTime and GeoPoint.

Building #

This library depends on node_interop package which provides Node.js bindings and build_node_compilers package which allows compiling Dart applications as Node.js modules.

To enable builders provided by build_node_compilers first add following dev dependencies to your pubspec.yaml:

  build_runner: ^1.0.0
  build_node_compilers: ^0.2.0

Next, create build.yaml file with following contents:

      - "lib/**"
      - "node/**" # Assuming your main Dart files is in node/ folder (recommended).
      - "test/**"
          compiler: dart2js # To compile with dart2js by default

You can now build your project using build_runner:

# By default compiles with DDC
pub run build_runner build --output=build

# To compile with dart2js:
pub run build_runner build \
  --define="build_node_compilers|entrypoint=compiler=dart2js" \
  --define="build_node_compilers|entrypoint=dart2js_args=[\"--minify\"]" \ # optional, minifies resulting code

Status #

This library is considered stable though not feature complete. It is recommended to check dev versions for latest updates and bug fixes.

Make sure to checkout after every release, all notable changes and upgrade instructions will be described there.

Current implementation coverage report:

  • [x] admin
  • [x] admin.auth
  • [x]
  • [x] admin.credential
  • [x] admin.database
  • [x] admin.firestore
  • [x] admin.messaging
  • [ ]

Features and bugs #

Please file feature requests and bugs at the issue tracker.

2.1.0 #

Upgraded to support firebase-admin Messaging features to send cloud message payloads to device, topic, all, multicast, and subscribe/unsubscribe from topic.

  NotificationMessagePayload notification = NotificationMessagePayload(
    title: title,
    body: body,
  MessagingPayload payload = new MessagingPayload(notification: notification, data: DataMessagePayload(data: {"doc" : event.reference.path}));
  MessagingDevicesResponse result = await firestoreApp.messaging().sendToDevice(token, payload);
  // or firestoreApp.messaging().sendToTopic(topic, payload);
  • Breaking change: Updated versions of many dependencies in pubspec

2.0.0 #

Upgraded to support firebase-admin Node.js SDK 8.0.0 or greater and @google-cloud/firestore 2.0.0.

Make sure to update your package.json with following version constraints:

  "dependencies": {
    "firebase-admin": "8.5.0",
    "@google-cloud/firestore": "2.0.0"
  • Breaking change: library now requires Node.js >= 8.13.0
  • Breaking change: DocumentReference getCollections method renamed to listCollections.
  • Breaking change: Firestore getCollections method renamed to listCollections.
  • Added support for Collection Groups in Firestore

1.2.2 #

  • Fixed issue with converting to JS types in startAt/startAfter/endAt/endAfter (#45).

1.2.1 #

  • Added support for updating nested fields in Firestore (#44)

1.2.0 #

  • Added Query.on and methods (#39).
  • Added EventType namespace for list of all event types supported by Query.on.
  • Added support for FieldValue.arrayUnion and FieldValue.arrayRemove in Firestore (#42).

1.1.0 #

Upgraded to support firebase-admin Node.js SDK 6.2.0 and @google-cloud/firestore 0.18.0.

Make sure to update your package.json with following version constraints:

  "dependencies": {
    "firebase-admin": "~6.2.0",
    "@google-cloud/firestore": "0.18.0"

Other updates:

  • Added Firestore.getAll() method.

Note that 6.2.0 of JS SDK introduced several breaking changes to JS APIs:

  • QuerySnapshot.docChanges is no more a field but a method QuerySnapshot.docChanges().
  • For query snapshots returned from DocumentQuery.get() all DocumentChanges now return their type as added instead of null.
  • GeoPoint no longer exposes toString method.

1.0.0 #

No functional changes in this version, it is published to replace obsolete 0.0.1 version on the Pub's package homepage to improve discoverability.

Ongoing work will continue in 1.0.0-dev.* branch until it's considered stable and feature complete. Make sure to checkout recent dev version for latest updates.

Non-breaking changes may be published to the stable track periodically.

Other updates:

  • Brought back dependency on quiver_hashcode (2.0.0) and removed copy-pasted implementation.

1.0.0-dev.24.0 #

  • Added Firestore.getCollections.
  • Added DocumentReference.getCollections.
  • Added and CollectionReference.path.

1.0.0-dev.23.0 #

  • Fixed Firestore queries with GeoPoint and Blob arguments.

1.0.0-dev.22.0 #

  • Fixed Firestore queries with Timestamps. (#35)

1.0.0-dev.21.0 #

  • Upgraded to latest node_interop and fixed declaration of FirebaseError class.

1.0.0-dev.20.0 #

This version introduces several fixes and breaking changes related to Firestore Timestamps. It also should be compatible with latest build_runner (1.0.0) and build_node_compilers (0.2.0).

Users are encouraged to start migrating to use Firestore Timestamps instead of DateTime objects as soon as possible. Read "Firestore Timestamps migration" in for more details.

  • Added: Firestore DocumentReference.parent (#30).
  • Added: Firestore Timestamp type.
  • Added: FirestoreSettings type and Firestore.settings() method which allows to control timestampsInSnapshots option for migration to new timestamps.
  • Breaking: DocumentSnapshot.createTime and DocumentSnapshot.updateTime now return an instance of new Timestamp type.
  • Deprecated: DocumentData.setDateTime and DocumentData.getDateTime are deprecated in favor of setTimestamp and getTimestamp accordingly.

1.0.0-dev.19.0 #

  • Temporarily removed dependency and copied hash functions from quiver_hashcode until it supports Dart 2 stable.

1.0.0-dev.18.0 #

  • Fixed: analysis warnings with latest Pub and Dart SDK, prepare for Dart 2 stable.

1.0.0-dev.17.0 #

  • Added: complex types support to Firestore lists
  • Breaking: removed generic type argument from DocumentData.setList and DocumentData.getList methods. Firestore does not enforce single type to all elements in a list, so having generic type on those methods was limiting.

1.0.0-dev.16.0 #

  • Fixed: strong mode errors with latest Dart 2 SDK (dev.68).

1.0.0-dev.15.0 #

  • Added: Firestore.runTransaction
  • Breaking: Firestore DocumentSnapshot.updateTime type changed to String from DateTime. This field contains ISO formatted datetime string with nanosecond precision and can't be converted to Dart's DateTime object without loosing information (DateTime only stores microseconds). This value should be treated as opaque when passed to any transaction as a precondition.
  • Fixed: dartdevc build by upgrading to latest build_runner.

1.0.0-dev.14.0 #

  • Fixed: Firestore, fixed error calling CollectionReference.document() without arguments.
  • Fixed: Firestore, fixed error calling DocumentQuery.where() with DocumentReference as value.

1.0.0-dev.13.0 #

  • Added: Firestore, support for SetOptions and WriteBatch (#14).

1.0.0-dev.12.0 #

  • Added: Firestore, support for Blob fields (#13).

1.0.0-dev.11.0 #

  • Fixed: Firestore, QuerySnapshot.documentChanges was wrongly testing for isEmpty (#11).

1.0.0-dev.10.0 #

  • Added: Firestore, support for select, offset, startAt, startAfter, endAt, endBefore, FieldValue.delete and FieldValue.timestamp (#8).
  • Deprecated: Firestore, deprecated createGeoPoint and createFieldPath functions. These will be hidden from public API before stable 1.0.0 release.
  • Added: Firestore, Firestore.documentId() function as a replacement for the library-level documentId() function. The library-level function is now deprecated and will be removed before stable 1.0.0 release.

1.0.0-dev.9.0 #

  • Upgraded to JS sdk v5.11.0
  • FirebaseAdmin.initializeApp can now be invoked without explicit credentials, in which case the app will be initialized with Google Application Default Credentials (introduced in JS SDK v5.9.1).

1.0.0-dev.8.0 #

  • Fixed: GeoPoint treated as invalid type when used in Firebase Functions.

1.0.0-dev.7.0 #

  • Added: Firebase Database Reference.transaction method.

1.0.0-dev.6.0 #

  • Added: following methods to Firebase Query: ref, endAt, equalTo, isEqual, limitToFirst, limitToLast, orderByChild, orderByKey, orderByPriority, orderByValue, startAt, toJson, toString.
  • Added: Firebase Database Reference.update method.

1.0.0-dev.5.0 #

  • Added: Auth service implementation. See App.auth() method and Auth class for more details.

1.0.0-dev.4.0 #

  • Breaking change: CollectionReference.add now expects instance of DocumentData instead of regular Dart Map. Use DocumentData.fromMap to upgrade from previous version.
  • Fixed: Handle nested maps in DocumentData.fromMap.

1.0.0-dev.3.0 #

  • Added: Firestore DocumentData.keys and DocumentData.toMap().

1.0.0-dev.2.0 #

  • Fixed: DocumentQuery.snapshots was subscribing to a wrong stream of updates.
  • Added: DocumentQuery.get.

1.0.0-dev.1.0 #

  • Breaking change: Depends on Dart SDK >= 2.0.0-dev.
  • Breaking change: Depends on node_interop >= 1.0.0-dev.
  • Breaking change: removed built_value integration.
  • Added: Firestore support.
  • Internal: run tests in both dart2js and dartdevc.
  • Updated documentation with new instructions.

0.1.0-beta.4 #

  • Breaking: FirebaseAdmin.initializeApp() now expects new AppOptions object as the first argument and optional name argument. See documentation for FirebaseAdmin.initializeApp() for more details and example.

0.1.0-beta.3 #

  • Updated JS bindings with type arguments for Promises.

0.1.0-beta.2 #

  • New: Preliminary support for built_value models and serializers.
  • Breaking: Removed Js prefix for interface classes.
  • Breaking: Credential got split in to CredentialService and Credential. Similar changes with Database and DatabaseService.
  • Upgraded to node_interop: 0.1.0-beta.4.
  • Consolidated all JS bindings in to one file.
  • Completed interface bindings for Realtime Database.
  • Added interface bindings for Firestore.
  • Many dartdoc updates for JS bindings.

0.1.0-beta.1 #

  • Breaking change: FirebaseAdmin.initializeApp() now accepts separate named arguments for credential and databaseURL
  • Breaking change: Credential.cert() now accepts separate named arguments for service account key parameters
  • New Credential.certFromPath() method added.
  • Added DataSnapshot.forEach().
  • Many dartdoc updates
  • Updated to node_interop 0.1.0-beta.1

0.0.1 #

  • Initial version


import 'package:firebase_admin_interop/firebase_admin_interop.dart';

main() async {
  final serviceAccountKeyFilename = '/absolute/path/to/service-account.json';
  final admin = FirebaseAdmin.instance;
  final cert = admin.certFromPath(serviceAccountKeyFilename);
  final app = admin.initializeApp(new AppOptions(
    credential: cert,
    databaseURL: "YOUR_DB_URL",
  final ref = app.database().ref('/test-path');
  // Write value to the database at "/test-path" location.
  await ref.setValue("Hello world");
  // Read value from the same database location.
  var snapshot = await ref.once("value");
  print(snapshot.val()); // prints "Hello world".

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:

  firebase_admin_interop: ^2.1.0

2. Install it

You can install packages from the command line:

with pub:

$ pub get

with Flutter:

$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:firebase_admin_interop/firebase_admin_interop.dart';
Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
Learn more about scoring.

We analyzed this package on Mar 31, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.7.1
  • pana: 0.13.6

Health suggestions

Fix lib/src/firestore.dart. (-25 points)

Analysis of lib/src/firestore.dart reported 64 hints, including:

line 22 col 17: Unnecessary new keyword.

line 76 col 12: Unnecessary new keyword.

line 88 col 12: Unnecessary new keyword.

line 95 col 12: Unnecessary new keyword.

line 113 col 45: Unnecessary new keyword.

Fix lib/src/database.dart. (-14.39 points)

Analysis of lib/src/database.dart reported 31 hints, including:

line 35 col 35: Unnecessary new keyword.

line 40 col 7: Unnecessary new keyword.

line 126 col 33: Unnecessary new keyword.

line 148 col 14: Unnecessary new keyword.

line 150 col 12: Unnecessary new keyword.

Fix lib/src/messaging.dart. (-6.78 points)

Analysis of lib/src/messaging.dart reported 14 hints, including:

line 69 col 7: DO use curly braces for all flow control structures.

line 71 col 7: DO use curly braces for all flow control structures.

line 80 col 7: DO use curly braces for all flow control structures.

line 82 col 7: DO use curly braces for all flow control structures.

line 92 col 7: DO use curly braces for all flow control structures.

Fix lib/src/admin.dart. (-2.48 points)

Analysis of lib/src/admin.dart reported 5 hints:

line 15 col 34: Unnecessary new keyword.

line 17 col 54: Unnecessary new keyword.

line 55 col 23: Unnecessary new keyword.

line 62 col 21: Unnecessary new keyword.

line 73 col 35: Unnecessary new keyword.

Fix lib/src/app.dart. (-1.99 points)

Analysis of lib/src/app.dart reported 4 hints:

line 32 col 28: Unnecessary new keyword.

line 37 col 21: Unnecessary new keyword.

line 42 col 22: Unnecessary new keyword.

line 47 col 22: Unnecessary new keyword.


Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.7.0 <3.0.0
js ^0.6.1+1 0.6.1+1
meta ^1.1.8 1.1.8
node_interop ^1.0.3 1.0.3
quiver_hashcode ^2.0.0 2.0.0
Dev dependencies
build_node_compilers ^0.2.4
build_runner ^1.7.4
build_test ^0.10.12+1
test ^1.12.0