View on GitHub

@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 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
  • Query class
    • Properties
    • Methods
  • DataSnapShot class
    • Properties
    • Methods
  • EventType
  • TransactionResult
• License

Intro ​

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

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)

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 ​

Methods ​

Reference class ​

The Reference class has the following properties:

Properties ​

Methods ​

The Reference class has the following methods:

| Method | Returns | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | child(path: string) | Reference | For the description, see child on Firebase documentation. | | onDisconnect() | OnDisconnect | For the description, see onDisconnect on Firebase documentation. | | push(value?: any, onComplete?: () => void) | IThenableReference | For the description, see push 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. | | setPriority(priority: string | number, onComplete?: (error: FirebaseError) => void) | Promise<void> | For the description, see setPriority on Firebase documentation. | | setWithPriority(newVal: any, newPriority: string | number, onComplete?: (error: FirebaseError) => void) | Promise<void> | For the description, see setWithPriority on Firebase documentation. | | transaction(transactionUpdate: (currentData: object) => object, onComplete?: (error: FirebaseError, committed: boolean, finalResult: any) => void, applyLocally: boolean = true) | Promise<TransactionResult> | For the description, see transaction on Firebase documentation. | | update(values: { [key: string]: any }, onComplete?: (error: FirebaseError) => void) | Promise<void> | For the description, see update on Firebase documentation. |

OnDisconnect class ​

Properties ​

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> | For the description, see setWithPriority on Firebase documentation. | | update(values: { [key: string]: any }, onComplete?: (error: FirebaseError) => void) | Promise<void> | For the description, see update on Firebase documentation. |

Query class ​

Properties ​

Methods ​

| Method | Returns | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | endAt(value: string | number | boolean, key?: string) | Query | For the description, see endAt on Firebase documentation. | | equalTo(value: string | number | boolean, key?: string) | Query | For the description, see equalTo on Firebase documentation. | | 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<DataSnapshot> | | 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) | Query | For the description, see startAt on Firebase documentation. |

DataSnapShot class ​

Properties ​

Methods ​

EventType ​

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

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

TransactionResult ​

License ​

Apache License Version 2.0