firebase_admin_interop 1.1.0

  • README.md
  • CHANGELOG.md
  • Example
  • Installing
  • Versions
  • 82

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:
dependencies:
  firebase_admin_interop: ^1.1.0

Run pub get.

  1. Create package.json file to install Node.js modules used by this library:
{
  "dependencies": {
    "firebase-admin": "6.2.0",
    "@google-cloud/firestore": "0.18.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:

dev_dependencies:
  build_runner: ^1.0.0
  build_node_compilers: ^0.2.0

Next, create build.yaml file with following contents:

targets:
  $default:
    sources:
      - "lib/**"
      - "node/**" # Assuming your main Dart files is in node/ folder (recommended).
      - "test/**"
    builders:
      build_node_compilers|entrypoint:
        options:
          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
  --output=build/

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 CHANGELOG.md after every release, all notable changes and upgrade instructions will be described there.

Current implementation coverage report:

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

Features and bugs

Please file feature requests and bugs at the issue tracker.

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 CollectionReference.id 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 README.md 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

example/main.dart

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:


dependencies:
  firebase_admin_interop: ^1.1.0

2. Install it

You can install packages from the command line:

with pub:


$ pub get

Alternatively, your editor might support 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';
  
Version Uploaded Documentation Archive
1.1.0 Nov 21, 2018 Go to the documentation of firebase_admin_interop 1.1.0 Download firebase_admin_interop 1.1.0 archive
1.0.0 Nov 20, 2018 Go to the documentation of firebase_admin_interop 1.0.0 Download firebase_admin_interop 1.0.0 archive
0.0.1 Jul 8, 2017 Go to the documentation of firebase_admin_interop 0.0.1 Download firebase_admin_interop 0.0.1 archive
1.0.0-dev.25.0 Nov 21, 2018 Go to the documentation of firebase_admin_interop 1.0.0-dev.25.0 Download firebase_admin_interop 1.0.0-dev.25.0 archive
1.0.0-dev.24.0 Nov 20, 2018 Go to the documentation of firebase_admin_interop 1.0.0-dev.24.0 Download firebase_admin_interop 1.0.0-dev.24.0 archive
1.0.0-dev.23.0 Oct 29, 2018 Go to the documentation of firebase_admin_interop 1.0.0-dev.23.0 Download firebase_admin_interop 1.0.0-dev.23.0 archive
1.0.0-dev.22.0 Oct 27, 2018 Go to the documentation of firebase_admin_interop 1.0.0-dev.22.0 Download firebase_admin_interop 1.0.0-dev.22.0 archive
1.0.0-dev.21.0 Oct 23, 2018 Go to the documentation of firebase_admin_interop 1.0.0-dev.21.0 Download firebase_admin_interop 1.0.0-dev.21.0 archive
1.0.0-dev.20.0 Oct 5, 2018 Go to the documentation of firebase_admin_interop 1.0.0-dev.20.0 Download firebase_admin_interop 1.0.0-dev.20.0 archive
1.0.0-dev.19.0 Aug 10, 2018 Go to the documentation of firebase_admin_interop 1.0.0-dev.19.0 Download firebase_admin_interop 1.0.0-dev.19.0 archive

All 30 versions...

Popularity:
Describes how popular the package is relative to other packages. [more]
64
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
82
Learn more about scoring.

We analyzed this package on Dec 5, 2018, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.1.0
  • pana: 0.12.7

Platforms

Detected platforms: web, other

Primary library: package:firebase_admin_interop/firebase_admin_interop.dart with components: js.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0-dev <3.0.0
js ^0.6.1 0.6.1+1
meta ^1.0.5 1.1.6
node_interop ^1.0.0-dev.11.0 1.0.0
quiver_hashcode ^2.0.0 2.0.0
Dev dependencies
build_node_compilers ^0.2.0
build_runner ^1.0.0
build_test any
test ^1.0.0