zenginehq / zn-backend-firebase

Helper module for working with znFirebase in Zengine backend plugins.

Backend Firebase

Helper module for working with znFirebase in Zengine backend Plugins.

Installation

npm i @zenginehq/backend-firebase --save

Usage

var $firebase = require('@zenginehq/backend-firebase')();

var workspaceId = 11111;

// Load data.
$firebase.load(workspaceId).then(function (data) {
  console.log('it works!', data);
  // data fetched from <firebaseRoot>/11111
}).catch(function (err) {
  console.error(err);
});

// Save data.
var dataObj = {
  'childRoute': someData
  // someData could be any data type,
  // but dataObj (2nd argument of .save()) must be an object
}

$firebase.save(workspaceId, dataObj).then(function () {
  console.log('success!');
  // someData was saved at <firebaseRoot>/11111/childRoute
}).catch(function (err) {
  console.error(err);
});

// Delete data.
var recordId = 222
var deleteObj = {}
deleteObj[recordId] = null

$firebase.save(workspaceId, deleteObj).then(function () {
  console.log('success!');
  // the firebase route <firebaseRoot>/11111/222
  // and all data it contained has been deleted
}).catch(function (err) {
  console.error(err);
})

// Use arrays to formulate complex Firebase paths for both loading and saving.
var formId = 222
var recordId = 333

$firebase.load([workspaceId, formId, recordId, 'settings']).then(function (data) {
  // This will expand to: <firebaseRoot>/11111/222/333/settings
  console.log('it works!', data);
}).catch(function (err) {
  console.error(err);
});

// You can also pass a long string if that's your thing.
$firebase.load('foo/bar/baz/' + workspaceId + '/etc');

Note about Deletions

Passing null as the second argument of .save will cause strange and unhelpful behavior. Instead, pass an object with the endpoint(s) as the key(s) and null as the value(s) for the second argument. See Firebase docs for the underlying .update() command that is called.

Ex:

// much regrets
$firebase.save([workspaceId, 'undesiredField'], null).then(function () {
  //etc...
})

// all the good vibes
$firebase.save(workspaceId, {'undesiredField': null}).then(function () {
  // great work, team!
});

Contributing

See contributing doc

API Docs

Full documentation

zn-backend-firebase's Issues

Silent Error/hang for .save()

I have had this experience a few times during development, where my save configuration isn't perfect (like passing null as second argument, for example), and instead of returning an error, it just silently hangs my backend service. As long as I passed the proper params, it would execute and return just fine, but I couldn't catch any errors. I can look into this in more detail to see what's wrong with the source code, but in the meantime I'll leave this issue here in case anyone else has an idea why that would (not) happen.

Breaking Change with Module API

The previous module API no longer works because of the way the methods are defined. Either the docs or the code should be updated.

Previous:
$firebase.load(workspaceId)

Current:
$firebase().load(workspaceId)