{"id":23666441,"url":"https://github.com/mismith/angularfire-helper","last_synced_at":"2025-12-11T04:30:16.293Z","repository":{"id":25775206,"uuid":"29213529","full_name":"mismith/angularfire-helper","owner":"mismith","description":"Simplifies common AngularFire interactions by enhancing the flexibility and portability of the `firebase` module.","archived":false,"fork":false,"pushed_at":"2015-11-19T21:13:11.000Z","size":38,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-29T07:30:05.481Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mismith.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-01-13T22:01:24.000Z","updated_at":"2022-06-13T23:24:40.000Z","dependencies_parsed_at":"2022-08-24T14:14:18.362Z","dependency_job_id":null,"html_url":"https://github.com/mismith/angularfire-helper","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mismith%2Fangularfire-helper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mismith%2Fangularfire-helper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mismith%2Fangularfire-helper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mismith%2Fangularfire-helper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mismith","download_url":"https://codeload.github.com/mismith/angularfire-helper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239674215,"owners_count":19678367,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-29T07:30:22.508Z","updated_at":"2025-12-11T04:30:16.263Z","avatar_url":"https://github.com/mismith.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AngularFire Helper\n\n[![GitHub version](https://badge.fury.io/gh/mismith%2Fangularfire-helper.svg)](http://badge.fury.io/gh/mismith%2Fangularfire-helper)\n\nSimplifies common [AngularFire](https://github.com/firebase/angularfire) interactions by enhancing the flexibility and portability of the `firebase` module. Primary advantages:\n\n- **cleaner code**; no need to maintain a `BASE_URL` or repeat `new Firebase(BASE_URL + path)`\n- **simpler dependencies**; inject only one service instead of three (`$firebaseObject`+`$firebaseArray`+`$firebaseAuth` \u0026rarr; `$firebaseHelper`)\n- **improved performance**; caches all three Firebase data types (reference, object, array)\n- **augmented 'joins'**; access normalized data via key-object-association\n- **added convenience**; add the missing `$update` method to `$firebaseObject`\n\n# Setup\n\n1. Include [AngularJS](http://angularjs.org/) (1.3.4+), [Firebase](http://www.firebase.com/?utm_medium=web\u0026utm_source=angularfire-helper) (2.2.3+), and [AngularFire](https://www.firebase.com/docs/web/libraries/angular/?utm_medium=web\u0026utm_source=angularfire-heler) (1.0.0+) dependencies, then this library (replace `X.X.X` with latest version)\n\n        \u003cscript src=\"//ajax.googleapis.com/ajax/libs/angularjs/1.3.4/angular.min.js\"\u003e\u003c/script\u003e\n        \u003cscript src=\"//cdn.firebase.com/js/client/2.2.3/firebase.js\"\u003e\u003c/script\u003e\n        \u003cscript src=\"//cdn.firebase.com/libs/angularfire/1.0.0/angularfire.min.js\"\u003e\u003c/script\u003e\n        \u003cscript src=\"//cdn.rawgit.com/mismith/angularfire-helper/X.X.X/angularfire-helper.min.js\"\u003e\u003c/script\u003e\n\n2. Include this library as a module dependency in your angular app (instead of `firebase`)\n\n        angular.module('my-app', ['firebaseHelper'])\n\n3. Set your Firebase namespace\n\n        .config(function ($firebaseHelperProvider) {\n            $firebaseHelperProvider.namespace('my-app');\n        })\n\n4. Include the `$firebaseHelper` service (in place of `$firebaseObject`, `$firebaseArray`, and `$firebaseAuth`)\n\n        .controller('AppCtrl', function ($scope, $firebaseHelper) {\n            $scope.myObject = $firebaseHelper.object('myObject');\n        })\n\n\n\n# API\n\n## $firebaseHelperProvider\n\n* `namespace(name)`\n\n    Gets or sets the name of your Firebase app, i.e. the subdomain part of a URL like: `https://\u003cname\u003e.firebaseio.com/`. You must configure this before calling any `$firebaseHelper` methods.\n\n    **Example**:\n\n        .config(function ($firebaseHelperProvider) {\n          $firebaseHelperProvider.namespace('my-app');\n        })\n\n* `demo(enable)`\n\n    Use a `firebaseio-demo.com` URL by passing boolean `true`. (Uses the default `firebaseio.com` otherwise.)\n\n    **Example**:\n\n        .config(function ($firebaseHelperProvider) {\n          $firebaseHelperProvider.demo(true);\n        })\n\n* `root(path)`\n\n    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).\n    \n    **Example**:\n    \n         // if all your data lives under `https://my-app.firebaseio.com/data/…`, then call:\n         \n        .config(function ($firebaseHelperProvider) {\n          $firebaseHelperProvider.root('data');\n        })\n\n\n## $firebaseObject\n\n* `$update(newData)`\n\n    **Returns**: the promise from `$firebaseObject.$save()`\n\n    **Replaces**: having to manually handle promise wrapping\n\n    **Example**:\n\n        // old (pseudo)\n        var child1 = $firebaseObject(new Firebase(BASE_URL + 'parent/child1'));\n        child1.$value = newValue;\n        child1.$save().then(function (child1) {});\n        \n        // new\n        $firebaseHelper.object('parent/child1').$update(dataObj).then(function (child1) {});\n\n\n## $firebaseHelper\n\n\u003ca name=\"arguments\"\u003e\u003c/a\u003e\n### Arguments…\n\nIf the first parameter in any functions below is one of the following:\n\n* a `Firebase` reference,\n* a `$firebaseObject`, or\n* a `$firebaseArray`\n\nThen 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.\n\n**Example**:\n\n    var ref  = $firebaseHelper.ref('parent'),\n        obj1 = $firebaseHelper.object(ref, 'child1/child2', 'child3'),\n        obj2 = $firebaseHelper.object('parent/child1/child2/child3');\n\n    // obj1 === obj2\n\n\n### Authentication\n\n* \u003ccode\u003eauth([[arguments…](#arguments)])\u003c/code\u003e\n\n    **Returns**: an Angular-augmented authentication object.\n\n    **Replaces**: `$firebaseAuth(ref)`.\n\n    **Example**:\n\n        var old = $firebaseAuth(new Firebase(BASE_URL + 'parent/child1'));\n        var new = $firebaseHelper.auth('parent/child1');\n\n        // old === new\n\n\n### Data Types\n\n* \u003ccode\u003eref([[arguments…](#arguments)])\u003c/code\u003e\n\n    **Returns**: a `Firebase` reference at the API level, _i.e._ with no angular enhancements.\n\n    **Replaces**: `new Firebase(BASE_URL + path)`.\n\n    **Example**:\n\n        var old = new Firebase(BASE_URL + 'parent/child1');\n        var new = $firebaseHelper.ref('parent/child1');\n\n        // old === new\n\n\n* \u003ccode\u003eobject([[arguments…](#arguments)][, asArray])\u003c/code\u003e\n\n    **Returns**: a `$firebaseObject`, or, if the last parameter === `true`, then a `$firebaseArray`.\n\n    **Replaces**: `$firebaseObject()` and `$firebaseArray()`, respectively.\n\n    **Example**:\n\n        var old = $firebaseObject(new Firebase(BASE_URL + 'parent/child1'));\n        var new = $firebaseHelper.object('parent/child1');\n\n        // old === new\n\n    and\n\n        var old = $firebaseArray(new Firebase(BASE_URL + 'parent/child1'));\n        var new = $firebaseHelper.object('parent/child1', true);\n\n        // old === new\n\n\n* \u003ccode\u003earray([[arguments…](#arguments)])\u003c/code\u003e\n\n    **Returns**: a `$firebaseArray`.\n\n    **Replaces**: shortcut for \u003ccode\u003e$firebaseHelper.object([[arguments…](#arguments)], true)\u003c/code\u003e.\n\n    **Example**:\n\n        var old = $firebaseArray(new Firebase(BASE_URL + 'parent/child1'));\n        var new = $firebaseHelper.array('parent/child1');\n\n        // old === new\n\n\n### Utility\n\n* \u003ccode\u003eload([[arguments…](#arguments)][, asArray])\u003c/code\u003e\n\n    **Returns**: a promise that resolves when the required resource is ready. The first param of the callback will be that loaded resource.\n\n    **Replaces**: shortcut for \u003ccode\u003e$firebaseHelper.object([[arguments…](#arguments)][, asArray]).$loaded()\u003c/code\u003e.\n\n    **Example**:\n\n        var old, new;\n\n        $firebaseArray(new Firebase(BASE_URL + 'parent/child1')).$loaded().then(function (child1) {\n          old = child1;\n        });\n        $firebaseHelper.load('parent/child1', true).then(function (child1) {\n          new = child1;\n        });\n\n        // once both loaded: old === new\n\n\n* \u003ccode\u003ejoin([keys…](#arguments), [values…](#arguments))\u003c/code\u003e\n\n    **Returns**: a `$firebaseJoin` array of key-value-associated objects. Both `keys…` and `values…` params work like \u003ccode\u003e[arguments…](#arguments)\u003c/code\u003e in that they can be strings, special Firebase data types, or arrays thereof.\n\n    **Replaces**: wrapper for custom `$firebaseJoin` service ([see below](#firebasejoin)).\n\n    **Example**:\n\n        var keys     = $firebaseHelper.ref('keys'),\n            myObject = $firebaseHelper.object('parent'),\n            joined   = $firebaseHelper.join(keys, [myObject, 'child1']);\n\n      `joined` contains all children of `/parent/child1` whose `$id`s are present in `/keys`\n\n\n\u003ca name=\"firebasejoin\"\u003e\u003c/a\u003e\n## $firebaseJoin\n\n* \u003ccode\u003e$firebaseJoin([keysRef, ]valuesRef)\u003c/code\u003e\n\n    **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:\n    \n        {\n          keys: {\n            value1: 'value1',\n            value3: 'value3'\n          },\n          parent: {\n            child1: {\n              value1: 1,\n              value2: 2,\n              value3: 3,\n              value4: 4\n            }\n          }\n        }\n    \n    \u003cp\u003e\u003c/p\u003e\n    \n        $firebaseJoin($firebaseHelper.ref('keys'), $firebaseHelper.ref('parent/child1')).$loaded(function (data) {\n          // data == [{$id: 'value1', $value: 1}, {$id: value3, $value: 3}];\n        });\n    \n    Can also be used with only one argument to get a `$firebaseArray` of `$firebaseObjects` for any path. _e.g._ \n    \n        $firebaseJoin($firebaseHelper.ref('parent/child1')).$loaded(function (data) {\n          // data == [{$id: 'value1', $value: 1}, {$id: 'value2', $value: 2}, {$id: 'value3', $value: 3}, {$id: value4, $value: 4}];\n        });\n\n### Manipulation\n\nAll `$firebaseArray`-like methods are provided, including new and augmented functionality:\n\n* `$add(data)`\n\n  Create a new object in `values` then create a key in `keys` to link it.\n\n  **Example**:\n\n      $firebaseJoin('keys', 'parent/child1').$add({name: 'Name'})\n\n  \u003ctable\u003e\n    \u003ctr\u003e\n      \u003ctd valign=\"top\"\u003e\u003cpre\u003e\n  {\n    keys: {\n      value1: 'value1',\n      value3: 'value3'\n    },\n    parent: {\n      child1: {\n        value1: 1,\n        value2: 2,\n        value3: 3,\n        value4: 4\n      }\n    }\n  }\u003c/pre\u003e\u003c/td\u003e\n      \u003ctd\u003e\u0026rarr;\u003c/td\u003e\n      \u003ctd\u003e\u003cpre\u003e\n  {\n    keys: {\n      value1: 'value1',\n      value3: 'value3',\n      '-JABCDE12345fghi0000': '-JABCDE12345fghi0000'\n    },\n    parent: {\n      child1: {\n        value1: 1,\n        value2: 2,\n        value3: 3,\n        value4: 4,\n        '-JABCDE12345fghi0000': {\n          name: 'Name'\n        }\n      }\n    }\n  }\u003c/pre\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/table\u003e\n\n* `$save(indexOrItem)`\n\n  Update an existing value object in `values` (without affecting `keys`).\n\n  **Example**:\n\n      var joined = $firebaseJoin('keys', 'parent/child1'),\n          value3 = joined.$getRecord('value3');\n\n      value3.$value += 2;\n      joined.$save('value3');\n\n      // can also do this instead:\n      value3.$value += 2;\n      value3.$save();\n\n  \u003ctable\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003cpre\u003e\n  {\n    keys: {\n      value1: 'value1',\n      value3: 'value3'\n    },\n    parent: {\n      child1: {\n        value1: 1,\n        value2: 2,\n        value3: 3,\n        value4: 4\n      }\n    }\n  }\u003c/pre\u003e\u003c/td\u003e\n      \u003ctd\u003e\u0026rarr;\u003c/td\u003e\n      \u003ctd valign=\"top\"\u003e\u003cpre\u003e\n  {\n    keys: {\n      value1: 'value1',\n      value3: 'value3'\n    },\n    parent: {\n      child1: {\n        value1: 1,\n        value2: 2,\n        value3: 5,\n        value4: 4\n      }\n    }\n  }\u003c/pre\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/table\u003e\n\n* `$remove(indexOrItem)`\n\n  Delete an existing value object from `values` then delete its key from `keys`.\n\n  **Example**:\n\n      $firebaseJoin('keys', 'parent/child1').$remove('value3')\n\n  \u003ctable\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003cpre\u003e\n  {\n    keys: {\n      value1: 'value1',\n      value3: 'value3'\n    },\n    parent: {\n      child1: {\n        value1: 1,\n        value2: 2,\n        value3: 3,\n        value4: 4\n      }\n    }\n  }\u003c/pre\u003e\u003c/td\u003e\n      \u003ctd\u003e\u0026rarr;\u003c/td\u003e\n      \u003ctd valign=\"top\"\u003e\u003cpre\u003e\n  {\n    keys: {\n      value1: 'value1'\n    },\n    parent: {\n      child1: {\n        value1: 1,\n        value2: 2,\n        value4: 4\n      }\n    }\n  }\u003c/pre\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/table\u003e\n\n* `$link(key)`\n\n  Add an existing value object based on its `key`.\n\n  **Example**:\n\n      $firebaseJoin('keys', 'parent/child1').$link('value3')\n\n  \u003ctable\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003cpre\u003e\n  {\n    keys: {\n      value1: 'value1'\n    },\n    parent: {\n      child1: {\n        value1: 1,\n        value2: 2,\n        value3: 3,\n        value4: 4\n      }\n    }\n  }\u003c/pre\u003e\u003c/td\u003e\n      \u003ctd\u003e\u0026rarr;\u003c/td\u003e\n      \u003ctd valign=\"top\"\u003e\u003cpre\u003e\n  {\n    keys: {\n      value1: 'value1',\n      value3: 'value3'\n    },\n    parent: {\n      child1: {\n        value1: 1,\n        value2: 2,\n        value3: 3,\n        value4: 4\n      }\n    }\n  }\u003c/pre\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/table\u003e\n\n* `$unlink(indexOrItem)`\n\n  Delete an existing key from `keys` but leave its value object intact in `values`.\n\n  **Example**:\n\n      $firebaseJoin('keys', 'parent/child1').$unlink('value3')\n\n  \u003ctable\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003cpre\u003e\n  {\n    keys: {\n      value1: 'value1',\n      value3: 'value3'\n    },\n    parent: {\n      child1: {\n        value1: 1,\n        value2: 2,\n        value3: 3,\n        value4: 4\n      }\n    }\n  }\u003c/pre\u003e\u003c/td\u003e\n      \u003ctd\u003e\u0026rarr;\u003c/td\u003e\n      \u003ctd valign=\"top\"\u003e\u003cpre\u003e\n  {\n    keys: {\n      value1: 'value1'\n    },\n    parent: {\n      child1: {\n        value1: 1,\n        value2: 2,\n        value3: 3,\n        value4: 4\n      }\n    }\n  }\u003c/pre\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/table\u003e\n\n\n### Utility\n\n* `$loaded([resolve[, reject]])`\n\n  Wait for all filtered value objects to load.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmismith%2Fangularfire-helper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmismith%2Fangularfire-helper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmismith%2Fangularfire-helper/lists"}