Fuel

Fuel is a lightweight provider useful for DRYing up common command and query operations across your angular services while maintaing a flat, scalable JSON data structure. This module is designed for angular services using:

• Firebase
• angularFire
• Geofire

I apologize if you aren't using these in your code, but you really need to get with the program.

Installation & Setup

$ npm install firebase.fuel --save

$ bower install firebase.fuel --save

1.) Include Fuel in your app dependencies.

angular.module("yourApp",['firebase.fuel']);

2.) Define your root url in a config block using the setRoot method.

(function(){
    "use strict";

    angular.module("yourApp")
			.constant("YOURURL","https://your-firebase.firebaseio.com")
			.config(function(fuelConfigurationProvider,YOURURL){
				 fuelConfigurationProvider.setRoot(YOURURL);
			});

})();

Repo Terminology

Though we are both literally on the same page right now, let's make sure we are figuratively as well:

1. main: Adjective reserved for any firebaseRef or angularFire service found at a direct child of your root firebaseRef.

2. nested: Adjective reserved for any firebaseRef or angularFire service found at a child of a main node.

3. index: used as the pros do.

For example:

/* mainArray - $firebaseArray 
*  https://your-firebase.firebaseio.com/trips */

/* mainRecord - $firebaseObject
* https://your-firebase.firebaseio.com/trips/tripId */

/* nestedArray - $firebaseArray
* https://your-firebase.firebaseio.com/trips/tripId/cities*/

/* nestedRecord - $firebaseObject
* https://your-firebase.firebaseio.com/trips/tripId/cities/cityId */

Usage

The Fuel provider takes 2 arguments:

	 fuel(path, options);

1. path: String of the Firebase node your angular service will manage. This should be a direct child of your root firebaseRef.

2. options: Options hash. See below.

Conventions

• Syntax: I've tried to keep naming conventions to a minimum. You can follow your own convention, however Fuel's defaults for nodes and arrays are plural nouns, while defaults for records, objects, and angular services singluar. The one exception is that the default Geofire node and service are both called "geofire".

Example:

(function(){
    "use strict";

    angular.module("yourApp")
	 .factory("trip", tripFactory)
	 .factory("geofire", geofireFactory);

	 /** @ngInject */
	 function tripFactory(fuel){
			return fuel("trips");
	 }

	 /** @ngInject */
	 function geofireFactory(fuel){
			return fuel("geofire");
	 }

})();

Again, you can follow your own convention and override the defaults for all operations on the main node. Nested arrays, however, are another story. Fuel follows the above naming convention for constructing CRUD methods for nested arrays and nested records. To mainpulate nested data using a different naming convention you can do so manually.

• SRP: Fuel cannot directly manipulate/query other main firebase nodes. To access other direct child nodes of your root firebaseRef, you can call methods on a few predefined services that are injected on initialization. Currently, these services are: 'session','user','geofire'.

Configuration

You can configure Fuel by adding predefined keys to the options hash. There are 6 core options.

options[key] | Type | Result -------------|------|------------- geofire| Boolean | adds methods to persist/query geospatial data to/in Geofire gps| Boolean | adds a simple API to your app's geofire service nestedArrays| Array | ["child","nodes"] session | Boolean | adds a simple API for your app's session service/object timeStamp | Boolean | adds timestamp properties to main and nested records user | Boolean | adds a simple API for your app's user service (and session as well)

gps vs geofire

These keys are confusing, and perhaps need to be renamed. Anyhow, in keeping with SRP, services that have geospatial data to persist and query are not responsible for actually executing the given queries/commands. So:

(function(){
    "use strict";

    angular.module("yourApp")
			.factory("trip", tripFactory)
			.factory("geofire", geofireFactory);

// a service that has gps data associated with its ontology
	 /** @ngInject */
	 function tripFactory(fuel){
			return fuel("trips",{
				gps: true
			});
	 }

// a service that has prefined methods for managing geospatial data
	 /** @ngInject */
	 function geofireFactory(fuel){
			return fuel("geofire",{
				 geofire: true
			});
	 }

})();

Geofire Interface

By adding geofire: true to the options hash, fuel will persist/query any location data on behalf of your other services.

Fuel separates longitude and latitude from other data associated with a location (eg, placeIds, reviews, etc.). This will allow you to associate more than one location with a given record. Fuel will persist non-coordinate data at a firebase Node (default name is geofire), and will then persist the given location's coordinates at a child node( default name is the same as the original record). See the example below. And, yes, you can change these default names. See below.

Additionally, through the GPS interface described in the next session, Fuel will,by default, attempt to update each new location with the primary key of the record(e.g., tripId). You must however expliticly provide the geofire service with the correct property names via the foreignKeys option. See following example.

(function(){
    "use strict";

    angular.module("yourApp")
			.factory("flights", flightsFactory)
			.factory("trips", tripsFactory)
			.factory("geofire", geofireFactory)

	 /*Two different types of records with location data
	 * https://your-firebase.firebaseio.com/trips
	 * https://your-firebase.firebaseio.com/flights*/

	 /** @ngInject */
	 function tripsFactory(fuel){
			return fuel("trips",{
				 gps: true
			});
	 }

	 /** @ngInject */
	 function flightsFactory(fuel){
			return fuel("flights",{
				 gps: true
			});
	 }


	 /* Make sure you add these nodes to your security rules.

	 * For all location-data
	 * https://your-firebase.firebaseio.com/geofire

	 * For all trip coordinates  
	 * https://your-firebase.firebaseio.com/geofire/trips 

	 * For all flight coordinates - 
	 * https://your-firebase.firebaseio.com/geofire/flights */

	 /** @ngInject */
	 function geofireFactory(fuel){
			return fuel("geofire",{
				 geofire: true,
				 foreignKeys: {
				 "trips": "tripId",  // your-fb.com/geofire/uniqueId/tripId must be defined
				 "flights": "flightId",  // your-fb.com/geofire/uniqueId/flightId must be defined.
				 }
			});
	 }

})();

Lastly, the default names for coordinates are lat and lon.
These keys are only necessary for communicating with your controller; Geofire follows its own methodology.

REQs:

• Your controller/view will need to save coordinates in a data object with lat/lon keys. See below for renaming these keys.
• Your app will need to specify an angular service responsible for geofire in order for fuel to work properly. Also, you must make sure your security rules allow for the nodes and properties described above.

GPS Interface

By adding gps: true to the options hash, fuel will:

• send location data to your Geofire services defined above
• save/remove a geofire Index in your main node
• add unique recordId as a property of any location Record. See example below to override this behavior.

REQs:

• Follow setup for Geofire interface
• Specify a geofire index in your security rules. See below for overriding the default names.
• By default, Fuel will try to add the main record's unique id to the geofire location. To opt-out of this functionality simply add addRecordKey: false to the options hash.

For example:

(function(){
    "use strict";

    angular.module("yourApp")
			.factory("trip", tripFactory);

	 /** @ngInject */
	 function tripFactory(fuel){
			return fuel("trips",{
				 gps: true,
				 addRecordKey: false
			});
	 }
	 //make sure that 'https://your-firebase.firebaseio.com/trips/tripId/locations' is defined!

}();

NestedArrays

By adding nestedArrays: [] to the options hash, fuel will construct a few methods for manipulating/querying nested arrays/records.
For example:

fuel("users",{
  nestedArrays: ["phones"]
});

/* Will expose the firebase node 'https://your-fb.com/users/userId/phones',
* via the following methods.
*/

phone(key)
phones()
addPhone(data)
getPhone(key)
loadPhone(key)
loadPhones()
removePhone(idxOrRec)
savePhone(rec)

Session Interface

By adding session: true to the options hash, fuel adds a very simple API for sharing data between your app's session and the given firebase node.

REQs:

• injector: fuel will try to inject a session service. Make sure it's available. See below for overriding these names.

• IdMethod: fuel also expects the session service to have a method for querying ids stored in session. The default is getId. See below for overriding this name.

Again, very simple but it allows your service to maintain a current Record with very little code.

TimeStamp

By adding timeStamp: true to the options hash, fuel will add createdAt and updatedAt properties to all persisted records. See below for overriding these default names.

Currently, fuel won't allow you to opt out of timestamps for nested records. Maybe for the next iteration.

REQs:

• Make sure you have added the timeStamp properties to your security rules

User Interface

By adding user: true to the options hash, fuel will:

• save/remove an index in your user object
• add a uid property to any record created in the main Array
• queries user records based on the user index or uid property

REQs

• index: fuel will look for an index with the same name as the main node. You need to specify the index in your security rules.

For example:

	 fuel("trips",{
			user: true
	 };
//make sure that 'https://your-firebase.firebaseio.com/users/userId/trips' is defined!

• injector: fuel will try to inject a user service. Make sure it's available. See below for overriding these names.

• uid: Your security rules will need to allow for a uid property. To opt-out of this functionality simply add uid: false to the options hash. You can also specify a a different name via the uidProperty option, as described below.

Note: This option also provides the session mngt functionality described above. No need to add session: true, however if you want to be redundant redundant, please be my guest.

Overriding Defaults

Here are the current defaults and the required options to override them.

Nodes and Services

options[key] | Type | Default Value -------------|------|-------------- geofireNode | String | "geofire" geofireService | String | "geofire" geofireIndex | String | "locations" points | String | path argument of the given fuel service sessionService | String | "session" sessionIdMethod | String | "getId" userNode | String | "users" userService | String | singular of userNode

Properties

options[key] | Type | Default Value -------------|------|-------------- createTime | String | "createdAt" latitude| String| "lat" longitude| String| "lon" uidProperty| String | "uid" updateTime| String | "updatedAt"

Authentication Helper

Fuel does not expose the $firebaseAuth service. To do so, inject fuelAuth. This factory will return a $firebaseAuth service at the url specified by the fuelConfigurationProvider, as specified above.

Contributing

Yes, please. Below should get you setup.

$ git clone https://github.com/bpietravalle/fuel.git
$ cd fuel
$ npm i && bower i # install dependencies
$ gulp test #run test suite once
$ gulp test:auto #watch files and run tests continually

Any pending tasks associated with this repo are tracked here.