@nativescript/firebase-database

Intro
Installation
Use @nativescript/firebase-database
API
License

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.

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

Files

README.md

Latest commit

History

README.md

File metadata and controls

@nativescript/firebase-database

Intro

Installation

Use @nativescript/firebase-database

Import the plugin

Create a database instance

Get or create a reference

Read a reference data

One-time read

Listen to real-time changes in a reference

Listen to events of a reference's child

Remove a reference event listener

Data querying

Ordering data

Limit the number of results

Writing data

Setting data

Updating data

Generate a new child reference

Remove data from a reference

Save data as transactions

API

Database class

Properties

Methods

Reference class

Properties

Methods

OnDisconnect class

Properties

Methods

Query class

Properties

Methods

DataSnapShot class

Properties

Methods

EventType

TransactionResult

License