firebase-rpc

Asynchronously execute remote functions through firebase.

Install

Install with npm:

$ npm install --save firebase-rpc

Usage

Server

// using `firebase-admin` for example, but this may be `firebase`
var firebase = require('firebase-admin');

// initialize firebase using the server credentials file from your firebase console
firebase.initializeApp({
  credential: require('./config.json'),
  databaseURL: 'your-firebase-url.firebaseio.com'
});

// create a firebase reference to pass to the server for storing queues and data
var ref = firebase.database.ref('path/to/my/ref');

var Server = require('firebase-rpc').Server;
var server = new Server({ref: ref});

// Add some tasks
// These are `composer` tasks and follow the same conventions as `assemble`, `generate`, and `verb`
server.task('foo', function(cb) {
  // data passed in from the client is on the `this.options` object
  var foo = this.options.foo || 'foo';
  cb(null, {foo: foo.toUpperCase()});
});

server.task('bar', function(cb) {
  // data passed in from the client is on the `this.options` object
  var bar = this.options.bar || 'bar';
  cb(null, {bar: bar.toUpperCase()});
});

// start listening to the task queue tasks to execute
server.listen();

Client

// using `firebase-admin` for example, but this may be the `firebase` web api
var firebase = require('firebase-admin');

// Initialize firebase using the server credentials file from your firebase console (use the web config if using in a web browser)
firebase.initializeApp({
  credential: require('./config.json'),
  databaseURL: 'your-firebase-url.firebaseio.com'
});

// Create a firebae reference to pass to the client. This should be the same reference the server is using
var ref = firebase.database.ref('path/to/my/ref');

var Client = require('firebase-rpc').Client;
var client = new Client({ref: ref});

// run a task
client.run('foo', {foo: 'this is foo'}, function(err, results) {
  if (err) return console.error(err);
  console.log(results);
  //=> { foo: 'THIS IS FOO' }
});

API

Server

Create a server instance that creates a firebase-queue instance to use for executing remote functions. Remote functions may be added to the server instance or through built-in commands from a client.

Example

var config = {
  ref: firebase.database().ref('path/to/rpc')
};

var server = new Server(config);

Params

• config {Object}: Configuration object containing the firebase database reference and additional options to configure the server.
• config.ref {Object}: firebase database reference specifying where firebase-rpc should store information (firebase-queue and function results)
• config.queue {Object}: Additional firebase-queue options to specify the number of workers and schemas to use (See firebase-queue for available options)

.listen

Start listening by creating a firebase-queue instance.

Example

server.listen();

Params

• options {Object}: Additional options to override default firebase-queue options passed into the constructor.
• returns {Object}: Instance of firebase-queue;

Client

Create a client instance that adds tasks to a firebase-queue and listens for results.

Example

var config = {
  ref: firebase.database().ref('path/to/rpc')
};

var client = new Client(config);

Params

• config {Object}: Configuration object containing the firebase database reference and additional options to configure the client.
• config.ref {Object}: firebase database reference specifying where firebase-rpc should store information (firebase-queue and function results)

.connect

Connect to the firebase database by setting up client metadata to let the server know if this client is connected or not. When the client disconnects, the metadata is removed. This is called in the [run][#run] method to ensure the client is connected before trying to execute any functions.

Example

client.connect();

.run

Run the specified server side task given the specified data and wait for the results.

Example

client.run('foo', {foo: 'bar'}, function(err, results) {
  if (err) return console.error(err);
  console.log(results);
  //=> {foo: 'BAR'}
});

Params

• name {String}: Name of the task to run on the server. Task must already be registered with the server.
• data {Object}: Optional data to pass to the server side task for running.
• cb {Function}: Callback function to be called when the server returns with results.

About

Related projects

• assemble: Get the rocks out of your socks! Assemble makes you fast at creating web projects… more | homepage
• composer: API-first task runner with three methods: task, run and watch. | homepage
• firebase-cron: Store and run cron jobs with firebase. | homepage
• generate: Command line tool and developer framework for scaffolding out new GitHub projects. Generate offers the… more | homepage
• verb: Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… more | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Please read the contributing guide for avice on opening issues, pull requests, and coding standards.

Building docs

(This document was generated by verb-generate-readme (a verb generator), please don't edit the readme directly. Any changes to the readme must be made in .verb.md.)

To generate the readme and API documentation with verb:

$ npm install -g verb verb-generate-readme && verb

Running tests

Install dev dependencies:

$ npm install -d && npm test

Author

Brian Woodward

• github/doowb
• twitter/doowb

License

Copyright © 2016, Brian Woodward. Released under the MIT license.

This file was generated by verb-generate-readme, v0.2.0, on November 28, 2016.