AngularFire Helper

Simplifies common AngularFire interactions by enhancing the flexibility and portability of the firebase module. Primary advantages:

cleaner code; no need to maintain a BASE_URL or repeat new Firebase(BASE_URL + path)
simpler dependencies; inject only one service instead of three ($firebaseObject+$firebaseArray+$firebaseAuth → $firebaseHelper)
improved performance; caches all three Firebase data types (reference, object, array)
augmented 'joins'; access normalized data via key-object-association
added convenience; add the missing $update method to $firebaseObject

Setup

Include AngularJS (1.3.4+), Firebase (2.2.3+), and AngularFire (1.0.0+) dependencies, then this library (replace X.X.X with latest version)

 <script src="//ajax.googleapis.com/ajax/libs/angularjs/1.3.4/angular.min.js"></script>
 <script src="//cdn.firebase.com/js/client/2.2.3/firebase.js"></script>
 <script src="//cdn.firebase.com/libs/angularfire/1.0.0/angularfire.min.js"></script>
 <script src="//cdn.rawgit.com/mismith/angularfire-helper/X.X.X/angularfire-helper.min.js"></script>

Include this library as a module dependency in your angular app (instead of firebase)
```
 angular.module('my-app', ['firebaseHelper'])
```

Set your Firebase namespace

 .config(function ($firebaseHelperProvider) {
     $firebaseHelperProvider.namespace('my-app');
 })

Include the $firebaseHelper service (in place of $firebaseObject, $firebaseArray, and $firebaseAuth)

 .controller('AppCtrl', function ($scope, $firebaseHelper) {
     $scope.myObject = $firebaseHelper.object('myObject');
 })

API

$firebaseHelperProvider

namespace(name)

Gets or sets the name of your Firebase app, i.e. the subdomain part of a URL like: https://<name>.firebaseio.com/. You must configure this before calling any $firebaseHelper methods.

Example:
```
  .config(function ($firebaseHelperProvider) {
    $firebaseHelperProvider.namespace('my-app');
  })
```
demo(enable)

Use a firebaseio-demo.com URL by passing boolean true. (Uses the default firebaseio.com otherwise.)

Example:
```
  .config(function ($firebaseHelperProvider) {
    $firebaseHelperProvider.demo(true);
  })
```

root(path)

Optional. Gets or sets the root path of your Firebase app's data. All $firebaseHelper calls will append this path to the base URL. Defaults to '' (empty).

Example:

   // if all your data lives under `https://my-app.firebaseio.com/data/…`, then call:
   
  .config(function ($firebaseHelperProvider) {
    $firebaseHelperProvider.root('data');
  })

$firebaseObject

$update(newData)

Returns: the promise from $firebaseObject.$save()

Replaces: having to manually handle promise wrapping

Example:

  // old (pseudo)
  var child1 = $firebaseObject(new Firebase(BASE_URL + 'parent/child1'));
  child1.$value = newValue;
  child1.$save().then(function (child1) {});
  
  // new
  $firebaseHelper.object('parent/child1').$update(dataObj).then(function (child1) {});

$firebaseHelper

Arguments…

If the first parameter in any functions below is one of the following:

a Firebase reference,
a $firebaseObject, or
a $firebaseArray

Then it will be detected as so, and the subsequent arguments will be treated as strings to be joined as a child path. The resulting node will therefore be a child of the first node.

Example:

var ref  = $firebaseHelper.ref('parent'),
    obj1 = $firebaseHelper.object(ref, 'child1/child2', 'child3'),
    obj2 = $firebaseHelper.object('parent/child1/child2/child3');

// obj1 === obj2

Authentication

auth([arguments…])

Returns: an Angular-augmented authentication object.

Replaces: $firebaseAuth(ref).

Example:

  var old = $firebaseAuth(new Firebase(BASE_URL + 'parent/child1'));
  var new = $firebaseHelper.auth('parent/child1');

  // old === new

Data Types

ref([arguments…])

Returns: a Firebase reference at the API level, i.e. with no angular enhancements.

Replaces: new Firebase(BASE_URL + path).

Example:
```
  var old = new Firebase(BASE_URL + 'parent/child1');
  var new = $firebaseHelper.ref('parent/child1');

  // old === new
```

object([arguments…][, asArray])

Returns: a $firebaseObject, or, if the last parameter === true, then a $firebaseArray.

Replaces: $firebaseObject() and $firebaseArray(), respectively.

Example:

  var old = $firebaseObject(new Firebase(BASE_URL + 'parent/child1'));
  var new = $firebaseHelper.object('parent/child1');

  // old === new

and

  var old = $firebaseArray(new Firebase(BASE_URL + 'parent/child1'));
  var new = $firebaseHelper.object('parent/child1', true);

  // old === new

array([arguments…])

Returns: a $firebaseArray.

Replaces: shortcut for $firebaseHelper.object([arguments…], true).

Example:

  var old = $firebaseArray(new Firebase(BASE_URL + 'parent/child1'));
  var new = $firebaseHelper.array('parent/child1');

  // old === new

Utility

load([arguments…][, asArray])

Returns: a promise that resolves when the required resource is ready. The first param of the callback will be that loaded resource.

Replaces: shortcut for $firebaseHelper.object([arguments…][, asArray]).$loaded().

Example:

  var old, new;

  $firebaseArray(new Firebase(BASE_URL + 'parent/child1')).$loaded().then(function (child1) {
    old = child1;
  });
  $firebaseHelper.load('parent/child1', true).then(function (child1) {
    new = child1;
  });

  // once both loaded: old === new

join(keys…, values…)

Returns: a $firebaseJoin array of key-value-associated objects. Both keys… and values… params work like arguments… in that they can be strings, special Firebase data types, or arrays thereof.

Replaces: wrapper for custom $firebaseJoin service (see below).

Example:
```
  var keys     = $firebaseHelper.ref('keys'),
      myObject = $firebaseHelper.object('parent'),
      joined   = $firebaseHelper.join(keys, [myObject, 'child1']);

`joined` contains all children of `/parent/child1` whose `$id`s are present in `/keys`
```

$firebaseJoin

$firebaseJoin([keysRef, ]valuesRef)

Returns: an augmented $firebaseArray of $firebaseObjects, including only the $firebaseObjects from valuesRef whose keys appear in the $firebaseArray at keysRef. i.e. Given a Firebase data structure like this:

  {
    keys: {
      value1: 'value1',
      value3: 'value3'
    },
    parent: {
      child1: {
        value1: 1,
        value2: 2,
        value3: 3,
        value4: 4
      }
    }
  }

  $firebaseJoin($firebaseHelper.ref('keys'), $firebaseHelper.ref('parent/child1')).$loaded(function (data) {
    // data == [{$id: 'value1', $value: 1}, {$id: value3, $value: 3}];
  });

Can also be used with only one argument to get a $firebaseArray of $firebaseObjects for any path. e.g.

  $firebaseJoin($firebaseHelper.ref('parent/child1')).$loaded(function (data) {
    // data == [{$id: 'value1', $value: 1}, {$id: 'value2', $value: 2}, {$id: 'value3', $value: 3}, {$id: value4, $value: 4}];
  });

Manipulation

All $firebaseArray-like methods are provided, including new and augmented functionality:

$add(data)

Create a new object in values then create a key in keys to link it.

Example:

$firebaseJoin('keys', 'parent/child1').$add({name: 'Name'})

{
  keys: {
    value1: 'value1',
    value3: 'value3'
  },
  parent: {
    child1: {
      value1: 1,
      value2: 2,
      value3: 3,
      value4: 4
    }
  }
}

→

{
  keys: {
    value1: 'value1',
    value3: 'value3',
    '-JABCDE12345fghi0000': '-JABCDE12345fghi0000'
  },
  parent: {
    child1: {
      value1: 1,
      value2: 2,
      value3: 3,
      value4: 4,
      '-JABCDE12345fghi0000': {
        name: 'Name'
      }
    }
  }
}

$save(indexOrItem)

Update an existing value object in values (without affecting keys).

Example:

var joined = $firebaseJoin('keys', 'parent/child1'),
    value3 = joined.$getRecord('value3');

value3.$value += 2;
joined.$save('value3');

// can also do this instead:
value3.$value += 2;
value3.$save();

{
  keys: {
    value1: 'value1',
    value3: 'value3'
  },
  parent: {
    child1: {
      value1: 1,
      value2: 2,
      value3: 3,
      value4: 4
    }
  }
}

→

{
  keys: {
    value1: 'value1',
    value3: 'value3'
  },
  parent: {
    child1: {
      value1: 1,
      value2: 2,
      value3: 5,
      value4: 4
    }
  }
}

$remove(indexOrItem)

Delete an existing value object from values then delete its key from keys.

Example:

$firebaseJoin('keys', 'parent/child1').$remove('value3')

{
  keys: {
    value1: 'value1',
    value3: 'value3'
  },
  parent: {
    child1: {
      value1: 1,
      value2: 2,
      value3: 3,
      value4: 4
    }
  }
}

→

{
  keys: {
    value1: 'value1'
  },
  parent: {
    child1: {
      value1: 1,
      value2: 2,
      value4: 4
    }
  }
}

$link(key)

Add an existing value object based on its key.

Example:

$firebaseJoin('keys', 'parent/child1').$link('value3')

{
  keys: {
    value1: 'value1'
  },
  parent: {
    child1: {
      value1: 1,
      value2: 2,
      value3: 3,
      value4: 4
    }
  }
}

→

{
  keys: {
    value1: 'value1',
    value3: 'value3'
  },
  parent: {
    child1: {
      value1: 1,
      value2: 2,
      value3: 3,
      value4: 4
    }
  }
}

$unlink(indexOrItem)

Delete an existing key from keys but leave its value object intact in values.

Example:

$firebaseJoin('keys', 'parent/child1').$unlink('value3')

{
  keys: {
    value1: 'value1',
    value3: 'value3'
  },
  parent: {
    child1: {
      value1: 1,
      value2: 2,
      value3: 3,
      value4: 4
    }
  }
}

→

{
  keys: {
    value1: 'value1'
  },
  parent: {
    child1: {
      value1: 1,
      value2: 2,
      value3: 3,
      value4: 4
    }
  }
}

Utility

$loaded([resolve[, reject]])

Wait for all filtered value objects to load.