angular-locker

A simple & configurable abstraction for local/session storage in angular projects

Only 0.8kb minified & gzipped!

Installation

via bower

$ bower install angular-locker

via npm

$ npm install angular-locker

manual

Simply download the zip file HERE and include dist/angular-locker.min.js in your project.

Usage

adding to your project

Add angular-locker as a dependency

angular.module('myApp', ['angular-locker'])

Configure via lockerProvider (optional)

.config(function config(lockerProvider) {
	lockerProvider.setStorageDriver('session');
	lockerProvider.setNamespace('myAppName');
}]);

inject locker into your controller/service/directive etc

.factory('MyFactory', function MyFactory(locker) {
	locker.put('someKey', 'someVal');
});

Adding items to locker

there are several ways to add something to locker:

You can add Objects, Arrays, whatever :)

locker will automatically serialize your objects/arrays in local/session storage

locker.put('someString', 'anyDataType');
locker.put('someObject', { foo: 'I will be serialized', bar: 'pretty cool eh' });
locker.put('someArray', ['foo', 'bar', 'baz']);
// etc

adding via value function param

Inserts specified key and return value of function

locker.put('someKey', function() {
	var obj = { foo: 'bar', bar: 'baz' };
	// some other logic
	return obj;
});

adding multiple items at once by passing a single object

This will add each key/value pair as a separate item in storage

locker.put({
	someKey: 'johndoe',
	anotherKey: ['some', 'random', 'array'],
	boolKey: true
});

adding via key function param

Inserts each item from the returned Object, similar to above

locker.put(function() {
	// some logic
	return {
		foo: ['lorem', 'ipsum', 'dolor'],
		user: {
			username: 'johndoe',
			displayName: 'Johnny Doe',
			active: true,
			role: 'user'
		}
	};
});

conditionally adding an item if it doesn't already exist

For this functionality you can use the add() method.

If the key already exists then no action will be taken and false will be returned

locker.add('someKey', 'someVal'); // true or false - whether the item was added or not

Retrieving items from locker

// locker.put('fooArray', ['bar', 'baz', 'bob']);

locker.get('fooArray'); // ['bar', 'baz', 'bob']

setting a default value

if the key does not exist then, if specified the default will be returned

locker.get('keyDoesNotExist', 'a default value'); // 'a default value'

retrieving multiple items at once

You may pass an array to the get() method to return an Object containing the specified keys (if they exist)

locker.get(['someKey', 'anotherKey', 'foo']);

// will return something like...
{
	someKey: 'someValue',
	anotherKey: true,
	foo: 'bar'
}

deleting afterwards

You can also retrieve an item and then delete it via the pull() method

// locker.put('someKey', { foo: 'bar', baz: 'bob' });

locker.pull('someKey', 'defaultVal'); // { foo: 'bar', baz: 'bob' }

// then...

locker.get('someKey', 'defaultVal'); // 'defaultVal'

all items

You can retrieve all items within the current namespace

This will return an object containing all the key/value pairs in storage

locker.all();

Checking item exists in locker

You can determine whether an item exists in the current namespace via

locker.has('someKey') // true or false

// e.g.
if (locker.has('user.authToken') ) {
	// we're logged in
} else {
	// go to login page or something
}

Removing items from locker

The simplest way to remove an item is to pass the key to the remove() method

locker.remove('keyToRemove');

removing multiple items at once

You can also pass an array to the remove method

locker.remove(['keyToRemove', 'anotherKeyToRemove', 'something', 'else']);

removing all within namespace

you can remove all the items within the currently set namespace via the clean() method

locker.clean();
// or
locker.setNamespace('someOtherNamespace').clean();

removing all items within the currently set storage driver

locker.empty();

Browser Compatibility

To check if the browser natively supports local and session storage, you can do the following:

if (! locker.supported()) {
	// load a polyfill?
}

I would recommend using Remy's Storage polyfill if you want to support older browsers.

For the latest browser compatibility chart see HERE

Development

$ npm install
$ bower install
$ gulp

License

The MIT License (MIT)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Eric013 / angular-locker