firebase-easy-query v1.0.1

What is firebase-easy-query

Firebase Easy Query (feq) is a small and simple library that goal simplify the traditional coding to manipulate Firebase database.

It's a proposal to try make easy and comprensible queries to Firebase.

Feq is thinked for beginners developers and small projects or simple developments.

Contents

• What is firebase-easy-query
  • Contents
  • Install
  • Adding feq to your JS project.
  • Instancing feq
  • Members
  • On(string)
  • Create([string], object)
  • Append(object)
  • Update(object)
  • From(string)
  • GetSnapshot()
  • GetValue()
  • Delete()
  • Remove(key, [condition])
  • CopyTo(string)
  • MoveTo(string)
  • From(string).SelectFor([...args])
  • From(string).Select(...args).Where(conditions)
  • Operators

Install

npm install firebase-easy-query --save

If you are developing with Google Cloud Functions sure you are using Node 8 engine.

Adding feq to your JS project.

const { feq, operator } = require("firebase-easy-query");

Instancing feq

Using a serviceAccountKey.json file

const serviceAccount = require("./serviceAccountKey.json");

const config = {
    credential: serviceAccount,
    databaseUrl: "https://your-firebase-db.firebaseio.com"
};

const db = new feq(config);

Specifying only the database name

const config = {
    databaseUrl: "https://your-firebase-db.firebaseio.com"
};

const db = new feq(config);

Using default credentials.

const db = new feq();

Setup firebase access config to instance using:

• Firebase JSON file config.
• initializeApp method.

Example

const serviceAccount = require("myServiceAccountKey.json");
const config = {
    credential: serviceAccount,
    databaseUrl: "https://my-firebase-database.firebaseio.com"
};

const db = new feq(config);

##Setting root node with SetRoot property

Use SetRoot property when you neeed setup a particular node as root.

db.SetRoot = '/my/Root/Path'

Important notes:

• When you set value for root, all queries will be executed over this path.
• If you don't set this property it use '/' as root or don't set a value.

Members

feq was wrote to use an intuitive syntax, to achieve it is use two single methods: On() and From().

On(string)

On() is a function that can use to create, delete, append or remove objects and single nodes over an custom or specific path.

Syntaxis

 db.On(path)

 db.On('/my/example/path')

Create(string, object)

Create a data set using a js object.

 let singleUserData = {
     fullName: "Victor Carbajal",
     age: 17,
     address: "Noth #98, CA"
 };

 db.On('/my/Single/Path').Create(singleUserData);

Create function has one overload that is useful to specify the firebase key node name:

 let singleUserData = {
     fullName: "Victor Carbajal",
     age: 17,
     address: "Noth #98, CA"
 };

 // in this case, it uses "customString" to named to dataset in singleUserData object.
 db.On('/my/Single/Path').Create('customString', singleUserData);

Append(object)

This function adds a new node with its value to an exists object

let myNode = {
	name: "Tom Smith",
    age: 32
};

db.On('/path/anyNode').Append(myNode);

// Or...

db.On('/path/anyNode').Append({ name: "Tom Smith", age: 32 });

##Rename(object) Re-sets the node name specified at the end part of path.

Mandatory object:

{ oldName: "oldOrOriginalValue", newName: "newValue" }

db.On(`/users/real`).Rename({ oldName: "user", newName: "user01" });

Update(object)

Updates the value of a node represent by the value of the On function parameter.

db.On(`/users/real/user01`).Update({ email: "jhonexamples@my-email.net" });

From(string)

Provides a set of functions that allow to you set new items on existing data. Specify the path to access to data tree that you wish affect.

GetSnapshot()

This function returns a promise.

Retrieves an object that represents an typically Firebase snapshot under once('value') statement.

let GetSnapshot = async () => {
    let snapshot = await db.From('/alphabetic/Alpha').GetSnapshot();
    let values = snapshot.val();
    let key = snapshot.key;
}

GetValue()

This function returns a promise.

Retrieves the value or object contained in the snapshot.

This function would be equivalent to invoke val() method from Firebase snapshot.

let GetValue = async () => {
    let value = await db.From('/alphabetic/Alpha').GetValue();
}

Delete()

Deletes the path specified inside From function.

Internally this action sets a null value.

// deletea the full tree accesible by '/my/Single/Path' path.
db.From('/my/Single/Path').Delete();

Remove(key, condition)

Remove the node in the tree data using the From(path) and the specific node name (key parameter).

To consider all nodes to find in object located in path you can use the character * (asterisk) as value for the key parameter.

Remove a node with a specific value, use the where object:

NOTE

The where object is NOT compatible with conditions object of Where member.

{
    where: {
        operator: operator.$eq,
        value: 'target-value'
    }
}

db.From(`/users/real`).Remove('*', {
    where: {
        operator: operators.$eq,
        value: true
    }
});

CopyTo(string)

This function creates a copy of data located in the path specified in From parameter, the new location will be that you set in the CopyTo function parameter.

db.From('/original/path').CopyTo('/my/New/Path');

MoveTo(string)

This function creates a copy from data in the specified path in From, then deletes the original data setting a null value.

db.From('/original/path').MoveTo('/my/New/Path');

From(string).SelectFor(...args)

Returns a set of objects whose values coincides with the key-names requested in SelectFor function.

To get all results from a snapshot, don't set a value for the args parameter of the SelectFor function.

From(string).Select(...args).Where(conditions)

Select: use this function to specify the properties or keys names (separated by commas) that you want retrieve.

To get all results from a snapshot, don't set a value for the args parameter of the Select function.

When you specify a set of names the process returns one or more (an array of) object with this properties.

If a property does not exists the default value in the returned object will be a empty string.

Select("name", "age", "address")

// This strings produce an object similar to
{
	name: any,
    age: any,
    address any
}

Retrieve a dataset using a object that contains property name to compare, operator and value.

let conditions = {
    where: {
        key: "name",
        operator: operator.$eq,
        value: "Richard"
    }
}

db.From('/users/user01').Select("name", "age", "address").Where(conditions);

Operators

Usage:

const { operator } = require("firebase-easy-query");

• Use $eq for equals to
• Use $gt for great than
• Use $ge for greater-than or equals
• Use $lt for less than
• Use $le for less-than or equals