scotttrinh / angular-localforage

Angular service & directive for https://github.com/mozilla/localForage (Offline storage, improved.)

angular-localForage

Angular service & directive for https://github.com/mozilla/localForage (Offline storage, improved.)

This angularJS module is a rewrite of angular-local-storage by grevory and angularLocalStorage by agrublev using the excellent Mozilla library localForage

---

Features :

• Store your data in the best available storage solution that your browser can offer (IndexedDB / WebSQL or localstorage as a fallback)

• All browsers are supported starting at IE8. For the full list check: IndexedDB support, WebSQL support and localstorage support

• Everything is async and uses promises

• Use the service or the directive

Usage :

• Download the project or install via bower bower install angular-localforage or npm npm install angular-localforage
• Download localForage https://github.com/mozilla/localForage
• Put localforage.js and angular-localForage.js into your project (with localforage.js before angular-localForage.js).

<script src="path/to/localforage.js"></script>
<script src="path/to/angular-localForage.js"></script>

• Add the module LocalForageModule to your application

angular.module('yourModule', ['LocalForageModule']);

• (optional) Configure the $localForageProvider. See below for details.
• Use the $localForage service or the local-forage directive

angular.module('yourModule', ['LocalForageModule'])
.controller('yourCtrl', ['$scope', '$localForage', function($scope, $localForage) {
    $localForage.setItem('myName','Olivier Combe').then(function() {
        $localForage.getItem('myName').then(function(data) {
            var myName = data;
        });
    });
}]);

<input local-forage="{key: 'autoStoredKey', name: 'myApp', scopeKey: 'myObj.myVar', defaultValue: 'this is the default value'}" ng-model="myObj.myVar" placeholder="This will be auto stored">

Functions :

• setDriver(driver): you can force the driver to use, check the localForage documentation for more information

• driver(): returns the current localForage driver (sync)

• setItem(key/Array<key>, value/Array<value>): stores data (async, promise)

• getItem(key/Array<key>, rejectIfNull): retrieves stored data, rejects if rejectIfNull is truthy and one of the values is null (async, promise)

localForage will return null for a lookup on a key that does not exist. If you set rejectIfNull to true, it will reject the promise if the value (or one of the values of the array lookup) is null. If you normally store null in the database, you can use the single arity version of the function to retrieve the null value, but you have no way to know if you've retrieved null or if the key did not exist.

• removeItem(key/Array<key>): removes stored data (async, promise)

• pull(key/Array<key>): removes stored data and returns it (it's like doing getItem followed by removeItem) (async, promise)

• clear(): removed all stored data for your application based on the app prefix (async, promise)

• key(n): retrieves the key at n position in storage. It doesn't take the prefix into account if you use localStorage (async, promise)

• keys(): returns all the keys used for storage in your application (async, promise)

• length(): returns the number of items stored (async, promise)

• iterate(iteratorCallback): Iterate over all value/key pairs in datastore. (async, promise)

Iterate supports early exit by returning non undefined value inside iteratorCallback callback. Resulting value will be passed to the promise as the result of iteration. You can use this to make a search in your data:

$localForage.iterate(function(value, key, iterationNumber) {
    if(angular.isInt(value) && value > 10) {
        return key;
    }
}).then(function(data) {
    // data is the key of the value > 10
});

• bind($scope, key/params object): lets you directly bind a LocalForage value to a $scope variable (async, promise)

$localForage.bind($scope, 'myStorageKey');

Note: It only binds when the object is already stored in the database or when you provide a default value.

$localForage.bind($scope, {
    key: 'myStorageKey', // required
    defaultValue: {test: 'my test'}, // a default value (needed if it is not already in the database)
    scopeKey: 'myObj.myVar', // the name of the scope key (if you want it to be different from key)
    name: 'myApp' // instance name
});

• unbind($scope, key[, scopeKey]): lets you unbind a variable from localForage while removing the value from both the scope and the storage (async, promise)

Directive :

You can directly bind a scope value from within your html. With the local-forage directive, you can either use just the key parameter:

<input local-forage="autoStoredKey" ng-model="autoStoredKey" placeholder="This will be auto stored">

Or give an object parameter:

<input local-forage="{key: 'autoStoredKey', name: 'myApp', scopeKey: 'myObj.myVar', defaultValue: 'this is the default value'}" ng-model="myObj.myVar" placeholder="This will be auto stored">

key is the only required parameter. The other options are:

• name: if you want to store your values in a specific instance (See below for more info on multiple instances)
• scopeKey: if you want to store the value in the scope under a different key from the one in storage. You can for example use a specific key of an object by using myObj.myVar
• defaultValue: if you want to define a ...default value

Configure the provider :

You can configure the $localForageProvider. Any parameter that you set here will be the default for any new localforage instance. You can for example set your own prefix for storage (by default lf is used).

angular.module('yourModule', ['LocalForageModule'])
.config(['$localForageProvider', function($localForageProvider){
    $localForageProvider.config({
        driver      : 'localStorageWrapper', // if you want to force a driver
        name        : 'myApp', // name of the database and prefix for your data, it is "lf" by default
        version     : 1.0, // version of the database, you shouldn't have to use this
        storeName   : 'keyvaluepairs', // name of the table
        description : 'some description'
    });
}]);

You can also choose to be notified by broadcast on set and remove.

angular.module('yourModule', ['LocalForageModule'])
.config(['$localForageProvider', function($localForageProvider){
    $localForageProvider.setNotify(true, true); // itemSet, itemRemove
}]);

The broadcast are the following :

$rootScope.$broadcast('LocalForageModule.setItem', {key: key, newvalue: value, driver: localforage.driver});
$rootScope.$broadcast('LocalForageModule.removeItem', {key: key, driver: localforage.driver});

Multiple instances

You can use multiple instances of localForage at the same time. To create a new instance, call createInstance with a config object (sync):

    var lf2 = $localForage.createInstance({
		name: '2nd',
		driver: 'localStorageWrapper'
	});

The parameters will inherit the default parameters that you might have configured in the config phase of your application (See above for details), but the new config object will overwrite them. It means that you can have one instance using localStorage, and one instance using indexedDB/WebSQL, at the same time ! The instance will take the name that you will define in the config object. You can get an instance previously created by using the instance method:

    var lf2 = $localForage.instance('2nd');

The instance method will return the default instance if you don't give a name parameter.

Unit tests

Download the required libs :

npm install
bower install

Then start the tests with :

gulp karma

It will launch Chrome and Firefox, edit the karma task in gulpfile.js if you want to change something. We could use more tests, see "contributing" below.

Contributing

I would love to have community contributions and support! A few areas where could use help right now:

• Writing tests
• Elaborating on documentation
• Creating examples for the docs
• Bug reports and/or fixes

If you want to contribute, please submit a pull request, or contact [email protected] for more information.

The commits messages need to be validated. Use the following commands to add a git hook that will check if you follow the convention :

• cd <angular-localForage-repo>
• ln -s ../../validate-commit-msg.js .git/hooks/commit-msg

When you commit your messages, follow this convention : <type>: <subject> <BLANK LINE> <optional message>

For example:

feat: Added validation commit msg file

Installation:
 * cd <angular-localForage-repo>
 * ln -s ../../validate-commit-msg.js .git/hooks/commit-msg

The following types are accepted in the commit messages:

• feat
• fix
• docs
• style
• refactor
• perf
• test
• chore
• revert

But only feat/fix/docs/perf will be in the changelog.

If you do a breaking change, add an explanation preceded by BREAKING CHANGE: . For example:

fix: remove deprecated promise unwrapping

BREAKING CHANGE: promise unwrapping has been removed.
It can no longer be turned on.

If you want to reference an issue, you can add a new line with either Closes or Fixes followed by the issue number. For example:

feat: Added changelog auto generation

Usage: gulp changelog

Fixes #62

You can fix / close multiple issue with one commit, just add a new line for each.

angular-localforage's Issues

$$hashKey is stored when $localForage is bound to a $scope.array used in an ngRepeat

this will eventually cause a $$hashKey collision, resulting in an unusable app.

getItem returns undefined if stored value is zero

if I use localforage instead of $localForage, the returned value is 0 as expected

Thanks for looking into it!

Additional Example

Hi there,

One super useful example might be, how to use a single database, but multiple stores.

The current example shows that database and store are set in the same config. If you had multiple stores inside of one database, it would be worthwhile to see how you could set the database at the app level, and set individual stores at the service level.

Is this something that'd be possible?

Please depend on angular <= 1.4.x

Cannot use in ionic?

I have added localForage and angular-localForage via bower.

When I launch the app with these dependencies:

angular.module('<appname>', [
      'ionic',
      'config',
      'ngCordova',
      'uuid4',
      'LocalForageModule'
    ])`

I have the module dependency error:

Error: [$injector:modulerr] Failed to instantiate module hsr001App due to:
 [$injector:modulerr] Failed to instantiate module LocalForageModule due to:
 [$injector:nomod] Module 'LocalForageModule' is not available!

I've tried with version 1.2.2 and 1.2.3, both are failing. Any Idea?

getItem/setItem promises are not called in tests

Hi,

I added a small test in my fork: https://github.com/SiegfriedEhret/angular-localForage/blob/master/tests/angular-localForage.js

It fails because promises are not called.
Do you have any idea about this ?

Thanks.

removeItem needs to use prefix

like setItem & getItem, removeItem needs to use the prefix: https://github.com/ocombe/angular-localForage/blob/master/angular-localForage.js#L85

ReferenceError: localforage is not defined

i use angular-localForage in service and result in ReferenceError: localforage is not defined

the following is my service code
angular.module('starter.services', ['G','LocalForageModule']). .factory('LoginService',function($http,HOST,$localForage) {
$localForage.setItem("a",1);
});

Binding to an element in an scope array

Is it possible to use the bind function to bind to a particular element in a scope array? e.g. if I wanted to bind a stored message array to the array scope.messages, I would do $localForage.bind($scope, 'messages').

But suppose I wanted to bind a particular stored message to a particular index within a scope array. Is there a way to do something like

$localForage.bind($scope, {
  key: 'message',
  scopeKey: 'messages[0]'
});

Thanks!

Set / Get multiple items

We should be able to get and set multiple items in one time by using an array as a key.

Documentation needs a comparison with ngStorage

angular-localForage functionality overlaps with that of ngStorage. A comparison between the two that describes when each is more appropriate should be added to the README.

Problem working with other $promisses.

Hello dude.

Becareful about $promise reference when the object contain $promises attribute.
In my case, I taken an object from $resource ($resource adds a $promise attr on my object by itself) and passing the same object to localForage it's not persisting.

If I set the $promise to null, before pass to localForage, it's stored.

IE error, TypeError: Unable to get property 'config' of undefined or null reference

Hi,

I'm new to angular and trying to implement localforage. Issue is probably my own ignorance , so my apologies upfront. Storing and getting via localforage all works well in Chrome and Firefox but the problem appears in IE (8-11). Specifically getting the error:

TypeError: Unable to get property 'config' of undefined or null reference

on line 58 of angular-localForage.js

It appears that the localforage object is not defined as I'm also getting an error (thrown before the error I mentioned above) with the localforage.js lib:

Object doesn't support this action

on line 1778.

I saw the previous issue #37 is similar so perhaps this is more of an issue for the localforage.js project?

Thanks for any insights you may provide.

Search example

Can you provide an example on how to search ($localForage.search)? Struggling in getting it to work.

Using RequireJS breaks angular-localForage

Hi, I'm using RequireJS at my project and I notice that when importing LocalForage, they don't register the global 'localforage' variable, so when this project looks for it an exception is raised.
Would be nice to add support for AMD/CommonJS module loading and be able of using this project in other environments.

bower angluar-localforage `config` is undefined

I followed through with the readme by installing both localforage and angular-localforage with bower.

I tried bundling both files with browserify and I keep getting the following error in chrome:

TypeError: Cannot read property 'config' of undefined
at new LocalForageInstance (http://localhost:3000/angular-localforage/dist/angular-localforage.js:57:17)

Prior to this error I was getting other errors in localforage about not being able to find the drivers and the promise library.

Any thoughts?

Problem with localforage.INDEXEDDB driver?

Is there a reason why using:

$localForageProvider.config({
            driver      : localforage.INDEXEDDB, // if you want to force a driver
            name        : 'myDb', 

would cause the error No available storage method found.

If I don't specify anything, it automatically falls back to WebSQL... I'm using the latest Chrome Version 42.0.2311.135 and according to http://caniuse.com/#search=indexeddb it should work :/

Help! :)

Unbind unexpected behavior

I've a scope variable that I'm watching at. Based on this variable I bind to a localForage key. In case of change, I want to unbind the 'old' value and bind the 'new'.

The current unbind method will delete the data stored for this key, what is not the intended behavior (the opposite of bind())

Either I'm wrong with my use-case and the usage of this library or unbind has a strange behavior.

To overcome my issue i currently I replaced the unbind method with:

LocalForageInstance.prototype.unbind = function unbind($scope, opts) {
        if(angular.isString(opts)) {
          opts = {
            key: opts
          }
        } else if(!angular.isObject(opts) || angular.isUndefined(opts.key)) {
          throw new Error("You must define a key to unbind");
        }

        var defaultOpts = {
          scopeKey: opts.key,
          name: defaultConfig.name
        };

        // If no defined options we use defaults otherwise extend defaults
        opts = angular.extend({}, defaultOpts, opts);

        var self = lfInstances[opts.name];

        if(angular.isUndefined(self)) {
          throw new Error("You must use the name of an existing instance");
        }

        // $parse(opts.scopeKey).assign($scope, null);
        if(angular.isDefined(watchers[opts.key])) {
          watchers[opts.key](); // unwatch
          delete watchers[opts.key];
        }
        return $q.when(true);
      };

Storage compression

We should offer a plugin to enable storage compression (see this article and this lib for examples).

key path and auto increment

Can I set up key path and auto increment by using localForage?

Getting null keys Fail when using webSQLStorage

Hi!

I got this error from angular-localForage:
Error: 'null' is not an object (evaluating 'key.indexOf')

The same code works well for IntexedDB and LocalStorage.

I tried to debug it and the problem lies around here:

promises.push(key(i).then(function(key) {
                            if(key.indexOf(p) === 0) {
                                keys.push(key.substr(p.length, key.length));
                            }
                        }));

and

var key = function(n) {
                var deferred = $q.defer(),
                    args = arguments;
                localforage.key(n).then(function success(key) {
                    deferred.resolve(key);
                }, function error(data) {
                    onError(data, args, key, deferred);
                });
                return deferred.promise;
            };

-> localforage.key(n)

This may be a localForage bug also.

Storage encryption

We could add an encryption functionality such as the one described in ngStore for Angular 2: https://docs.google.com/document/d/1DMacL7iwjSMPP0ytZfugpU4v0PWUK0BT6lhyaVEmlBQ/edit#heading=h.57girrphcre7
And something like that maybe: https://github.com/jas-/secStore.js

Cannot add to ionic manually.

I have tried to add this to ionic manually using the methods defined here.

I get an error message saying that localforagemodule is not defined. Or I get a message $localForage is not defined.

Documentation is inconsistent. Says $localforage and $localForage.

Method pull

I should add a method named pull that would get a key and delete it from storage at the same time (based on this idea)

Cannot add to ionic project

Hi,

I am trying to add this library to my ionic project, but the result of command

ionic add angular-localforage

is

Failed to find the bower component "angular-localforage".
Are you sure it exists? (CLI v1.3.21)

Your system information:

OS: Windows 8
Node Version: v0.10.33
Cordova CLI: 4.2.0
Ionic CLI Version: 1.3.21



add [name] ................................  Add an Ion, bower component, or addon to the project
                                             [name] The name of the ion, bower component, or addon you wish to install

If I run

bower install angular-localforage

I get:

bower angular-localforage#*     cached git://github.com/ocombe/angular-localForage.git#1.2.2
bower angular-localforage#*   validate 1.2.2 against git://github.com/ocombe/angular-localForage.git#*
bower localforage#1.2.0         cached git://github.com/mozilla/localForage.git#1.2.0
bower localforage#1.2.0       validate 1.2.0 against git://github.com/mozilla/localForage.git#1.2.0

Unable to find a suitable version for localforage, please choose one:
    1) localforage#1.2.0 which resolved to 1.2.0 and is required by angular-localforage#1.2.2
    2) localforage#~1.2.2 which resolved to 1.2.2 and is required by iPushPullPrefix the choice with ! to persist it to bower.json

Seems like the latest version is incompatible with latest version of localforage?

i read the code and fund a careless bug

at the 106 line of the angular-localForage.js
it should be if(notify.removeItem) but if(notify.setItem).
because in the condition it broadcast removeItem event

How to set up incremental key?

It is not actually an issue. But I don't know where to ask a question like this. In javascript (indexedDB), one can use an objectstore.app() function to store value into a key, which is incremental automatically. like

key value
0 {object1}
1 {object2}

The setitem() function in localForage could not accomplish this. Is there a simple function I can use to make that happen, or I have to use service to setup a logic?

Thanks.

Update search to use iterate

There is a new function iterate in localForage that should be released soon.
We should use it for the search method, it would be a lot more efficient.
ping @GaelMagnan

Doesn't work when using Electron

Initialization code doesn't detect NodeJs when using Electron.

Inconsistent naming in bower

The file is angular-localForage.js but the folder is named angular-localforage (because of the name attribute in bower.json). Would it be feasible to update the name to angular-localForage to be consistent with the repo and file?

Setting a prefix doesn't work

$localForageProvider.config({
  name: 'ab' // name of the database and prefix for your data
});

But calling $localForage.prefix() returns an empty string and 'ab' is not applied when setting items.

Bad detection method for Node.JS

By using this method to detect if the code is being executed by Node.JS, browserify compatibility is broken.

else if(typeof exports === 'object') {
        module.exports = factory(root.angular, require('localforage')); // Node
    } 

Add support for ArrayBuffer

When dealing with binary types, angular-localForage seems to have trouble handling 'ArrayBuffer' type.
The vanilla localForage lib doesn't have this problem.

To reproduce the problem, just try to cache an ArrayBuffer & then retrieve it. The resulting object is empty.

So far, with only a simple change on line 123, I managed to solve it :
From
localCopy = typeof Blob !== 'undefined' && value instanceof Blob ? value : angular.copy(value);
To
localCopy = typeof Blob !== 'undefined' && typeof ArrayBuffer !== 'undefined' && (value instanceof Blob || value instanceof ArrayBuffer) ? value : angular.copy(value);

However, I cannot run the test suite because of

'Failed to start Sauce Connect'.

I may however have missed something special for dealing with ArrayBuffer with angular-localForage.

Getting results in sync

Is there a way to get results in sync?

I am using the following factory

.factory('test', function($localForage) {
var data = [];
$localForage.getItem('data').then(function(result){ data = result;} )

return {
getData : return data;
}
}

unfortunately it always returns an empty dataset

Listener leak

It seems the setItem function leaks memory (listeners);

Been debugging this from within our app (Sweebr/Issues#381), back to this module now. Need to check if this module is the leak or localForage itself is leaking.

Using your example;

var storeDataI = 0;
function storeData() {
  if( storeDataI > 50 ) { return false; }
  setTimeout(function() {
     $scope.store('sometext');
     ++storeDataI;
     storeData();
  }, 1000);
}

storeData();

How to set array Item and get array Item ?

I read docs but i can't set array. how to set array ?

Can you make more easy array example ?

my array is $scope.test_arr = [{title: "test1", desc:"desc1"},{title: "test2", desc:"desc2"}]

Thank you

Could not make the example work

A newbie here. Have installed angular-localForage through node.js, and redirect all the script files to the right path. Couldn't get the save button to save input value to local storage.

Use console.log() to debug. No errors shown when load up the page and angular should be working. But console.log() stop working right after $localForage.setItem(...).

I have also tried the examples from the Mozila-localForage and that one works just fine. I didn't change a thing except for reseting the path for script files, no idea what is wrong...

update to newest localForage

it's been about 1 month since the last commit. I'd like to use this but I can't since it's missing some commits from mozilla/localForage that fix several issues.

for example: localForage/localForage#253

please update :)

Grunt bower-install injects backbone js

I noticed that an automatic injection of the bower dependencies in the html file by using a "grunt bower-install" command injects this:

<script src="bower_components/localforage/dist/localforage.min.js"></script>
<script src="bower_components/localforage/dist/backbone.localforage.min.js"></script>
<script src="bower_components/angular-localForage/angular-localForage.js"></script>

The backbone file will throw a syntax error when loading. It should not be there I guess...

bind() doesn't return the value as the comment suggests.

The source comment for bind() suggests that it returns the stored value, but the promise it returns only contains undefined.

getItem returns undefined for un-found key (rather than null)

The localForage documentation indicates that something like:

localforage.getItem('foo').then(function(data) {
  console.log(data);
});

should show data as null, if there's no key named 'foo' in the localForage storage systems.

The localforage library itself returns null in this case, but if I use the angular wrapper to call $localForage.getItem('foo'), the promise resolves with undefined instead of null. This is a little different from expected behavior, which made my if (data === null) code not quite detect key-not-found issues.

License

Under which license angular-localForage is published? Right now i can't find any infos. Maybe you could add a LICENSE file?

"Failed to execute 'put' on 'IDBObjectStore': An object could not be cloned."

I'm trying to setItem an object and receiving the above error. It's infuriating because I'm overwriting the same object with a couple of properties on child objects changed/added, and yet something's not right with it.

I don't know if this is an issue with this library or with localForage itself, or with the data I'm passing but if you've seen it before please let me know! Cheers.

Get multiple Items issue

Hi, I got an issue with the getItem method.

I'm using the right syntax :
$localForage.getItem(wkkeys).then(function(w) {..});

With wkkeys being an array of keys, but the function is never executed.
Any clue for this issue? I really don't understand what is going on.

Thanks

set prefix not working with localstorage

Hi,
I'm having issues with the new way of setting a prefix with localstorage. (Seems to work with IndexedDB though)

When forcing the use for localstorage for debugging and setting a custom prefix:

// configure localForage
.config(function ($localForageProvider) {
    $localForageProvider.config({
        driver: 'localStorageWrapper',
        name: 'webGUI'
    });
});

I end up with the prefix localforage/lfp instead.

Can you reproduce this behaviour?

bind does not support named database and falsy options

1/

 var defaultOpts = {
          scopeKey: opts.key,
          name: defaultConfig.name
        };

name should not be defaultConfig.name but the instance database name

2/

 return self.getItem(opts.key).then(function(item) {
          if(item) { // If it does exist assign it to the $scope value
            model.assign($scope, item);
          } else if(opts.defaultValue) { // If a value doesn't already exist store it as is
            model.assign($scope, opts.defaultValue);
            self.setItem(opts.key, opts.defaultValue);
          }
...
})

when item evaluates to false, defaultValue overwrittes current value
test should be : typeof item!=='undefined'
the same issue occurs for opts.defaultValue

Testing setItem() does not trigger promise

I noticed while writing unit tests that setItem() doesn't trigger the promise in tests. If I add $rootScope.$apply(); after resolve function it'll work though, but it's in the $localForage code so I'm out of luck. Do you prefer some other way of doing it or can this be fixed somehow?

Reasoning behind $rootScope.$apply(); with unit tests:
https://docs.angularjs.org/api/ng/service/$q#differences-between-kris-kowal-s-q-and-q

LocalForge 0.30

Hi mate,
thank you for yours great work! I have a question for you. Can you make bower install angular-localForage compatible with lastest localForage release (0.30) ? Now it has dependencies with 0.20 version. Thank you =)

Is it possible to create multiple dataStore in same db using angular-localForage?

Hi there. Is it possible to have multiple dataStore in IndexedDB using angular-localForage?
I tried this:

var $tblStage = $localForage.createInstance({
    storeName   : 'tblStage', // name of the table
});

but it triggered an error which says:

Error: A localForage instance with the name dbName is already defined.

I've read this Question before but, is the only way is working with Raw IndexedDB? Or I missed something in my code? Any Idea?

Question about bind and client-side models

I have a couple related questions:

1. If I bind the same LocalForage value to $scope variables in different parts of my app (e.g. two different directives), will a change to the LocalForage value automatically update the $scope values for both directives?

2. I'm thinking of using angular-localForage to create a common client-side model of my app that my different views can then access in order to keep elements synchronized which are accessed in multiple places. Is that a reasonable approach? Is there a place to read best practices for this?

3. Building on question 2 (best practices): What are best practices for storing model data in angular-localForage which has associations? e.g. if I have a bunch of rooms, each of which have a bunch of users, then I need to store all the users per room. Should I only store user id's per each room key? The downside to doing this is that I'd need to make a ton of calls binding to localForage. However, if I store full users per each room key, then it's going to be a big headache trying to keep them all in sync.

Thanks!