Skip to content

Latest commit

 

History

History
496 lines (365 loc) · 24.7 KB

README.md

File metadata and controls

496 lines (365 loc) · 24.7 KB

@nativescript/firebase-database

Intro

A plugin that allows you to add Firebase Realtime Databse to your NativeScript app.

Note: Use this plugin with the @nativescript/firebase-core plugin to initialize Firebase. NativeScript Firebase provides integration with the Android & iOS Firebase SDKs, supporting both realtime data sync and offline capabilities.

image

Installation

Install the plugin by running the following command in the root directory of your project.

npm install @nativescript/firebase-database

Use @nativescript/firebase-database

Note The Firebase documentation provides great examples of best practices on how to structure your data. We highly recommend reading the guide before building out your database.

Import the plugin

Make the Realtime Database SDK available to your app by importing it once, in the app.ts file.

import '@nativescript/firebase-database'; // only needs to be imported 1x

Create a database instance

To create a new Firebase Database instance, call the database method on the firebase instance as follows:

import { firebase } from '@nativescript/firebase-core';

const database = firebase().database();

By default, this allows you to interact with Firebase Database using the default Firebase App used whilst installing Firebase on your platform. If however you'd like to use a secondary Firebase App, pass the secondary app instance when calling the database method:

import { firebase } from '@nativescript/firebase-core';
import '@nativescript/firebase-database';

// create secondary app instance
const config = new FirebaseOptions();
const secondaryApp = firebase.initializeApp(config, 'SECONDARY_APP');

const database = firebase().database(secondaryApp);

Get or create a reference

A core concept to understanding Realtime Database is references - a reference to a specific node within your database. A node can be a specific property or sub-nodes.

To create a Reference, call the ref method on the database instance passing it the path of the reference:

import { firebase } from '@nativescript/firebase-core';

const reference = firebase().database().ref('/users/123');

Read a reference data

You can read a reference data in two ways: once or whenever there is a change in the reference or its children.

One-time read

To read the value once, call the once method on a reference passing it the value event name:

import { firebase } from '@nativescript/firebase-core';

firebase()
	.database()
	.ref('/users/123')
	.once('value')
	.then((snapshot) => {
		console.log('User data: ', snapshot.val());
	});

Listen to real-time changes in a reference

To set up an active listener to react to any changes to the node and its children, call the on method passing it the value event as the first parameter and the event handler as the second paramater:

import { firebase } from '@nativescript/firebase-core';

firebase()
	.database()
	.ref('/users/123')
	.on('value', (snapshot) => {
		console.log('User data: ', snapshot.val());
	});

The event handler will be called straight away with the snapshot data, and further called when any changes to the node occur.

Listen to events of a reference's child

To listen any of the following events of a reference's child, call the on method on the reference passing it the event name as the first argument and the event handler as the second argument. pass the event name to the on method as first argument and, as a second argument, pass The above example demonstrates how to subscribe to events whenever a value within the node changes. In some cases, you may need to only subscribe to events whenever a child node is

  • child_added
  • child_changed
  • child_removed _ child_moved

If you are listening to a node with many children, only listening to data you care about helps reduce network bandwidth and speeds up your application.

import { firebase } from '@nativescript/firebase-core';

const ref = firebase()
	.database()
	.ref('/users');

const onChildAdd = ref
	.on('child_added', (snapshot) => {
		console.log('A new node has been added', snapshot.val());
	});

// Stop listening for updates when no longer required
ref.off('child_added', onChildAdd);

Remove a reference event listener

To unsubscribe from an event, call the off method on the reference passing it the event name and the function that the on method returned. This can be used within any useEffect hooks to automatically unsubscribe when the hook needs to unsubscribe itself.

import { firebase } from '@nativescript/firebase-core';

const ref = firebase()
	.database()
	.ref(`/users/${userId}`);

const onValueChange = ref
	.on('value', (snapshot) => {
		console.log('User data: ', snapshot.val());
	});

// Stop listening for updates when no longer required
ref.off('value', onValueChange);

Note: The off method requires the same ref as specified on the corresponding on method. The event handler specified in the on method must be unique. If a common event handler is used for multiple events, an anonymous function can be used to invoke the common handler.

Data querying

Realtime Database provides support for basic querying of your data. When a reference node contains children, you can both order & limit the returned results.

If your application requires more advanced query capabilities, it is recommended you use Cloud Firestore. For available query API, see the Query class.

Ordering data

By default, results are ordered based on the node keys. However, if you are using custom keys you can order your data by calling one of the orderBy* methods a Query instance.

For example, if all of the children nodes are scalar values (string, number or boolean) you can use the orderByValue method, and Firebase will automatically order the results. The example below would return the def node before the abc node:

import { firebase } from '@nativescript/firebase-core';

/*
 * {
 *   'scores': {
 *     'abc: 30,
 *     'def': 50,
 *   }
 * }
 */

const scores = await firebase().database().ref('scores').orderByValue().once('value');

Please note that the ordering will not be respected if you do not use the forEach method provided on the DataSnapshot.

scores.forEach((snapShot)=>{
	// do someting
})

Limit the number of results

You can limit the number of results returned from a query by using one of the limitTo* methods. For example, to limit to the first 10 results, you call the limitToFirst(10) on the reference:

import { firebase } from '@nativescript/firebase-core';

const users = firebase().database().ref('users').limitToFirst(10).once('value');

Firebase also provides the ability to return the last set of results in a query via the limitToLast method.

Instead of limiting to a specific number of documents, you can also start from, or end at a specific reference node value:

import { firebase } from '@nativescript/firebase-core';

await firebase().database().ref('users').orderByChild('age').startAt(21).once('value');

Writing data

You write data to a reference using either the set or update method.

Setting data

Calling the set method on a Reference overwrites all of the existing data at that reference node. The value can be anything; a string, number, object etc:

import { firebase } from '@nativescript/firebase-core';

firebase()
	.database()
	.ref('/users/123')
	.set({
		name: 'Ada Lovelace',
		age: 31,
	})
	.then(() => console.log('Data set.'));

If you set the value to null, Firebase will automatically class the node as removed, and delete it from the database.

Updating data

Rather than overwriting all existing data, the update method updates any existing data on the reference node. Firebase automatically merges the data depending on what currently exists.

import { firebase } from '@nativescript/firebase-core';

firebase()
	.database()
	.ref('/users/123')
	.update({
		age: 32,
	})
	.then(() => console.log('Data updated.'));

Generate a new child reference

To generate a new child reference for a reference, call the push on the reference optionally passing the value to store. The push method automatically generates a new key. To store a value in the child reference, call the set method passing the value to store.

import { firebase } from '@nativescript/firebase-core';

const newReference = firebase().database().ref('/users').push();

console.log('Auto generated key: ', newReference.key);

newReference
	.set({
		age: 32,
	})
	.then(() => console.log('Data updated.'));

The keys generated are ordered to the current time, so the list of items returned from Firebase will be chronologically sorted by default.

Remove data from a reference

To remove data from a reference, call the remove method on the reference:

import { firebase } from '@nativescript/firebase-core';

await firebase().database().ref('/users/123').remove();

Optionally, you can also set the value of a reference node to null to remove it from the database:

import { firebase } from '@nativescript/firebase-core';

await firebase().database().ref('/users/123').set(null);

Save data as transactions

Transactions are a way to always ensure a write occurs with the latest information available on the server. Transactions never partially apply writes & all writes execute at the end of a successful transaction.

Imagine a scenario where an app can "like" user posts. Whenever a user presses the "Like" button, the /likes/:postId value (number of likes) on the database increments. Without transactions, we'd first need to read the existing value and then increment that value in two separate operations.

On a high-traffic application, the value on the server could already have changed by the time the operation sets a new value, causing the actual number to not be consistent.

Transactions remove this issue by atomically updating the value on the server. If the value changes whilst the transaction is executing, it will retry. This always ensures the value on the server is used rather than the client value.

To execute a new transaction, call the transaction method on a reference:

import { firebase } from '@nativescript/firebase-core';

function onPostLike(postId) {
	const reference = firebase().database().ref(`/likes/${postId}`);

	// Execute transaction
	return reference.transaction((currentLikes) => {
		if (currentLikes === null) return 1;
		return currentLikes + 1;
	});
}

// When post "567" is liked
onPostLike('567').then((transaction) => {
	console.log('New post like count: ', transaction.snapshot.val());
});

API

Database class

The database class has the following members.

Properties

Property Type Description
android com.google.firebase.database.FirebaseDatabase A readonly database instance for Android.
ios FIRDatabase A readonly database instance for iOS.
app FirebaseApp readonly
persistenceCacheSizeBytes number
persistenceEnabled boolean

Methods

Method Returns Description
constructor(app?: FirebaseApp) void Creates a Firebase Realtime Database instance.
useEmulator(host: string, port: number) void For the description, see useEmulator on Firebase documentation.
refFromURL(url: string) Reference For the description, see refFromURL on Firebase documentation.
setLoggingEnabled(enabled: boolean) void
ref(path?: string) Reference Returns a Reference instance.
goOffline() void For the description, see goOffline on Firebase documentation.
goOnline() void For the description, see goOnline on Firebase documentation.

Reference class

The Reference class has the following properties:

Properties

Property Type Description
android com.google.firebase.database.Reference A readonly native Android instance the Reference class.
ios FIRDatabaseReference A readonly native iOS instance the Reference class.
key string readonly. For the description, see key on Firebase documentation.
parent Reference readonly. For the description, see parent on Firebase documentation.
ref Reference readonly. For the description, see ref on Firebase documentation.
root Reference readonly. For the description, see root on Firebase documentation.

Methods

The Reference class has the following methods:

Method Returns
child(path: string) Reference
onDisconnect() OnDisconnect
push(value?: any, onComplete?: () => void) IThenableReference
remove(onComplete?: (error: FirebaseError) => void) Promise<void>
set(value: any, onComplete?: (error: FirebaseError) => void) Promise<void>
`setPriority(priority: string number, onComplete?: (error: FirebaseError) => void)`
`setWithPriority(newVal: any, newPriority: string number, onComplete?: (error: FirebaseError) => void)`
transaction(transactionUpdate: (currentData: object) => object, onComplete?: (error: FirebaseError, committed: boolean, finalResult: any) => void, applyLocally: boolean = true) Promise<TransactionResult>
update(values: { [key: string]: any }, onComplete?: (error: FirebaseError) => void) Promise<void>

OnDisconnect class

Properties
Property Type Description
android com.google.firebase.database.OnDisconnect readonly
ios FIRDatabaseReference readonly
Methods
Method Returns Description
cancel(onComplete?: (error: FirebaseError) => void) Promise<void> For the description, see cancel on Firebase documentation.
remove(onComplete?: (error: FirebaseError) => void) Promise<void> For the description, see remove on Firebase documentation.
set(value: any, onComplete?: (error: FirebaseError) => void) Promise<void> For the description, see set on Firebase documentation.
`setWithPriority(value: any, priority: string number, onComplete?: (error: FirebaseError) => void)` Promise<void>
update(values: { [key: string]: any }, onComplete?: (error: FirebaseError) => void) Promise<void> For the description, see update on Firebase documentation.

Query class

Properties

Property Type Description
android com.google.firebase.database.Query A readonly Android instance of the Query class.
ios FIRDatabaseQuery A readonly iOS instance of the Query class.
ref Reference A Reference instance to the Query's location.

Methods

Method Returns Description
`endAt(value: string number boolean, key?: string)`
`equalTo(value: string number boolean, key?: string)`
keepSynced(bool: boolean)
limitToFirst(limit: number) Query For the description, see limitToFirst on Firebase documentation.
limitToLast(limit: number) Query For the description, see limitToLast on Firebase documentation.
off(eventType?: EventType, callback?: (a: DataSnapshot, b: string) => void, context?: Record<string, any>) void
`on(eventType: EventType, callback: (data: DataSnapshot, previousChildKey: string) => void, cancelCallbackOrContext?: (a: FirebaseError) => void Record<string, any>, context?: Record<string, any>)` (a: DataSnapshot, b: string) => void
`once(eventType: EventType, successCallback?: (a: DataSnapshot, b: string) => any, failureCallbackContext?: (a: FirebaseError) => void Record<string, any>): Promise`
orderByChild(path: string) Query For the description, see orderByChild on Firebase documentation.
orderByKey() Query For the description, see orderByKey on Firebase documentation.
orderByPriority() Query For the description, see orderByPriority on Firebase documentation.
orderByValue() Query For the description, see orderByValue on Firebase documentation.
`startAt(value: string number boolean, key?: string)`

DataSnapShot class

Properties

Property Type Description
android com.google.firebase.database.DataSnapshot readonly
ios FIRDataSnapshot readonly
key string readonly
ref Reference readonly

Methods

Method Returns Description
child(path: string) DataSnapshot For the description, see child.
exists() boolean For the description, see exists on Firebase documentation.
exportVal() void For the description, see exportVal on Firebase documentation.
forEach(action: (child: DataSnapshot) => true) boolean Find the descriptin forEach
getPriority() string | number For the description, see getPriority on Firebase documentation.
hasChild(path: string) boolean For the description, see hasChild on Firebase documentation.
hasChildren() boolean For the description, see hasChildren on Firebase documentation.
numChildren() number For the description, see numChildren on Firebase documentation.
val() void For the description, see val on Firebase documentation.

EventType

The EventType consists can be any of the following event names:

  • 'value'
  • 'child_added'
  • 'child_changed'
  • 'child_moved'
  • 'child_removed'

TransactionResult

Property Type
snapshot DataSnapshot
committed boolean

License

Apache License Version 2.0