npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

cordova-firestore-dropin

v3.0.0

Published

A Google Firebase Firestore plugin aiming at being a drop-in replacement for the firebase-js-sdk

Downloads

8

Readme

Cordova Firestore Plugin

A Google Firebase Firestore plugin to enable realtime synchronisation between app and cloud and automatically handle limited connectivity.

This plugin aims at being a drop-in replacement for the firebase-js-sdk to make supporting the web platform easier, and to ease the transition for cordova applications built with the javascript SDK.

What is Firestore?

From the Google documentation (https://firebase.google.com/docs/firestore/):

Cloud Firestore is a flexible, scalable database for mobile, web, and server development from Firebase and Google Cloud Platform. Like Firebase Realtime Database, it keeps your data in sync across client apps through realtime listeners and offers offline support for mobile and web so you can build responsive apps that work regardless of network latency or Internet connectivity. Cloud Firestore also offers seamless integration with other Firebase and Google Cloud Platform products, including Cloud Functions

Supported platforms

This plugin supports the following platforms:

  • Android
  • iOS
  • Browser # As of version 2.0 browser support is deprecated and will be dropped or refactored in the future in favor of a transparent firebase-js-sdk implementation

Installation

Install the plugin

cordova plugin add cordova-plugin-firestore --save

or

phonegap plugin add cordova-plugin-firestore

Optional installation variables for Android

ANDROID_FIREBASE_CORE_VERSION

Version of com.google.firebase:firebase-core. This defaults to 16.0.8.

ANDROID_FIREBASE_FIRESTORE_VERSION

Version of com.google.firebase:firebase-firestore. This defaults to 18.2.0.

You can find the latest versions of these here.

Android specific installation

Download google-services.json to (your_project_dir)/google-services.json

Hint: Get a config file for your Android App

You must ensure that google-services.json is put in the correct location. This can be achieved using the following in your config.xml:

<platform name="android">
    <resource-file src="google-services.json" target="app/google-services.json" />
</platform>

Dependencies

cordova-support-google-services

In order to ensure Firebase initialises correctly on Android this plugin can be used. This is not automatically added as a dependency to allow for the configuration it performs to be done manually if desired.

iOS specific installation

Download GoogleService-Info.plist to (your_project_dir)/GoogleService-Info.plist

Hint: Get a config file for your iOS App

You must ensure that GoogleService-Info.plist is put in the correct location. This can be done as follows:

<platform name="ios">
    <resource-file src="GoogleService-Info.plist" />
</platform>

Keychain Sharing Capability

If using multiple Firebase plugins it may be necessary to enable this.

Firestore configuration

It is good practice to make sure your Firestore database is only accessible for authorised users, at least for write operations. It is recommended you take time to understand Firestore rules.

An example that only allows access for authorised users is shown below:

service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read, write : if request.auth != null;
    }
  }
}

Authenticating users is beyond the scope of this plugin, but the cordova-plugin-firebase-authentication is one such plugin you can use to achieve this which will work alongside this plugin.

Dependencies

Promises

This plugin uses Promises. If you want to use this with Android 4.4 then you will need to include a Promise polyfill.

Example

A simple example is shown below which sets up the necessary options, initialises the database and then adds a document to a users collection:

var options = {
  "datePrefix": '__DATE:',
  "fieldValueDelete": "__DELETE",
  "fieldValueServerTimestamp" : "__SERVERTIMESTAMP",
  "persist": true,
  "config" : {}
};

if (cordova.platformId === "browser") {

  options.config = {
    apiKey: "(your api key)",
    authDomain: "localhost",
    projectId: "(your project id)"
  };
}

Firestore.initialise(options).then(function(db) {
  // Add a second document with a generated ID.
  db.get().collection("users").add({
      first: "Alan",
      middle: "Mathison",
      last: "Turing",
      born: 1912
  })
  .then(function(docRef) {
      console.log("Document written with ID: ", docRef.id);
  })
  .catch(function(error) {
      console.error("Error adding document: ", error);
  });
});

options.config

In the above example this is being used for the browser version, but it can also be used for Android and iOS to specify different databases than the default in the google-services.json and GoogleService-Info.plist files.

What is supported?

Firestore

  • collection(collectionPath)
  • runTransaction(updateFunction)
  • batch # NOT SUPPORTED
  • doc(id)

DocumentSnapshot and QueryDataSnapshot

  • data()
  • get(fieldPath)
  • exists
  • id
  • ref

QuerySnapshot

  • docs
  • empty
  • size

DocumentReference

  • collection(collectionPath)
  • delete()
  • get()
  • onSnapshot(optionsOrObserverOrOnNext, observerOrOnNextOrOnError, onError)
  • set(data, options)
  • update(data)
  • id
  • parent

Query

  • endAt(snapshotOrVarArgs)
  • endBefore(snapshotOrVarArgs)
  • limit(limit)
  • orderBy(field, direction)
  • get()
  • onSnapshot(callback, options)
  • startAfter(snapshotOrVarArgs)
  • startAt(snapshotOrVarArgs)
  • where(fieldPath, opStr, passedValue)

CollectionReference (inherits from Query)

  • add(data)
  • id
  • doc(id)
  • parent

Transaction

  • get()
  • delete()
  • set()
  • update()

FieldValue

  • FieldValue.delete()
  • FieldValue.serverTimestamp()

GeoPoint

  • Firestore.GeoPoint(latitude, longitude)

Timestamp

  • Firestore.Timestamp(seconds, nanoseconds)

Dates

Because data is transferred to the client as JSON there is extra logic in place to handle the conversion of dates for some operations.

When initialising the plugin you can set up a prefix that is applied to a string value which is used to identify it as a date. The default prefix is __DATE:

Therefore, when a date field is retrieved from the database by the native code it will be transferred in the JSON looking similar to the following:

{
    "dateField" : "__DATE:123456789"
}

The number is seconds since epoch.

The client will receive the field as a Javascript Date.

This conversion also happens when specifying a field in a where condition.

timestampsInSnapshots

By default this option is set to false to mirror the current default. This explains the setting.

Not setting this to true will result in the following message when running in the browser:

The behavior for Date objects stored in Firestore is going to change
AND YOUR APP MAY BREAK.
To hide this warning and ensure your app does not break, you need to add the
following code to your app before calling any other Cloud Firestore methods:

  const firestore = firebase.firestore();
  const settings = {/* your settings... */ timestampsInSnapshots: true};
  firestore.settings(settings);

With this change, timestamps stored in Cloud Firestore will be read back as
Firebase Timestamp objects instead of as system Date objects. So you will also
need to update code expecting a Date to instead expect a Timestamp. For example:

  // Old:
  const date = snapshot.get('created_at');
  // New:
  const timestamp = snapshot.get('created_at');
  const date = timestamp.toDate();

Please audit all existing usages of Date when you enable the new behavior. In a
future release, the behavior will change to the new behavior, so if you do not
follow these steps, YOUR APP MAY BREAK.

FieldValue constants

Similar to the situation with dates, there are special values used for FieldValue values:

  • FieldValue.delete() equates to __DELETE
  • FieldValue.serverTimestamp() equates to __SERVERTIMESTAMP

These values can be changed when initialisation is performed.

Nested collections

Nested collections are supported. This can take either form as follows:

db.get().collection("mycollection").doc("mydoc").collection("mysubcollection");
db.get().collection("mycollection/mydoc/mysubcollection");

Note that the second form is slightly more efficient as it results in less objects being instantiated.

Learnings and notes

I have learnt a number of things whilst implementing this:

  • The documentation states that the database cannot be initialised in a seperate thread when using persistence. In my experience this should say it cannot be used in multiple threads.
  • When used on Android ensure that at least com.google.gms:google-services:3.1.1 is used in build dependencies. Earlier versions did not work for me.
  • Yes, I did spell initialise() with an 's' - Original plugin developer @ReallySmallSoftware is from the UK