angular-locker
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/angular-locker package

    2.0.5 • Public • Published

    angular-locker

    A simple & configurable abstraction for local/session storage in angular projects - providing a fluent api that is powerful and easy to use.

    Build Status Code Climate Test Coverage License NPM Release NPM Monthly Downloads

    Installation

    via bower

    $ bower install angular-locker

    via npm

    $ npm install angular-locker

    via jsDelivr CDN

    http://www.jsdelivr.com/#!angular.locker

    manual

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

    1.66 KB Minified & gzipped.

    Usage

    Adding to your project

    Add angular-locker as a dependency

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

    Configure via lockerProvider (optional)

    .config(['lockerProvider', function config(lockerProvider) {
        lockerProvider.defaults({
            driver: 'session',
            namespace: 'myApp',
            separator: '.',
            eventsEnabled: true,
            extend: {}
        });
    }]);

    Note: You can also pass false to namespace if you prefer to not have a namespace in your keys.

    inject locker into your controller/service/directive etc

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

    Extending Locker

    You can pass in an implementation of the Storage Interface to the lockerProvider as described above. e.g.

    lockerProvider.defaults({
        extend: {
            myCustomStore: function () {
                // getItem
                // setItem
                // removeItem
                // etc
            }
        }
    });
     
    // then use as normal
    locker.driver('myCustomStore').put('foo', 'bar');

    See my storageMock for an example on how to define a custom implementation.


    Switching storage drivers

    There may be times where you will want to dynamically switch between using local and session storage. To achieve this, simply chain the driver() setter to specify what storage driver you want to use, as follows:

    // put an item into session storage
    locker.driver('session').put('sessionKey', ['some', 'session', 'data']);
     
    // this time use local storage
    locker.driver('local').put('localKey', ['some', 'persistent', 'things']);

    Switching namespace

    // add an item within a different namespace
    locker.namespace('otherNamespace').put('foo', 'bar');

    Omitting the driver or namespace setters will respect whatever default was specified via lockerProvider.


    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;
    });

    The current value will be passed into the function so you can perform logic on the current value, before returning it. e.g.

    locker.put('someKey', ['foo', 'bar']);
     
    locker.put('someKey', function(current) {
        current.push('baz');
     
        return current;
    });
     
    locker.get('someKey'); // = ['foo', 'bar', 'baz']

    If the current value is not already set then you can pass a third parameter as a default that will be returned instead. e.g.

    // given locker.get('foo') is not defined
    locker.put('foo', function (current) {
        // current will equal 'bar'
    }, 'bar');

    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();
    // or
    locker.namespace('somethingElse').all();

    counting items

    To count the number of items within a given namespace:

    locker.count();
    // or
    locker.namespace('somethingElse').count();

    Checking item exists in locker

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

    locker.has('someKey'); // true or false
    // or
    locker.namespace('foo').has('bar');
     
    // 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 forget() method

    locker.forget('keyToRemove');
    // or
    locker.driver('session').forget('sessionKey');
    // etc..

    removing multiple items at once

    You can also pass an array.

    locker.forget(['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.namespace('someOtherNamespace').clean();

    removing all items within the currently set storage driver

    locker.empty();

    Events

    There are 3 events that can be fired during various operations, these are:

    // fired when a new item is added to storage
    $rootScope.$on('locker.item.added', function (e, payload) {
        // payload is equal to:
        {
            driver: 'local', // the driver that was set when the event was fired
            namespace: 'locker', // the namespace that was set when the event was fired
            key: 'foo', // the key that was added
            value: 'bar' // the value that was added
        }
    });
    // fired when an item is removed from storage
    $rootScope.$on('locker.item.forgotten', function (e, payload) {
        // payload is equal to:
        {
            driver: 'local', // the driver that was set when the event was fired
            namespace: 'locker', // the namespace that was set when the event was fired
            key: 'foo', // the key that was removed
        }
    });
    // fired when an item's value changes to something new
    $rootScope.$on('locker.item.updated', function (e, payload) {
        // payload is equal to:
        {
            driver: 'local', // the driver that was set when the event was fired
            namespace: 'locker', // the namespace that was set when the event was fired
            key: 'foo', // the key that was updated
            oldValue: 'bar', // the value that was set before the item was updated
            newValue: 'baz' // the new value that the item was updated to
        }
    });

    Binding to a $scope property

    You can bind a scope property to a key in storage. Whenever the $scope value changes, it will automatically be persisted in storage. e.g.

    app.controller('AppCtrl', ['$scope', function ($scope) {
     
        locker.bind($scope, 'foo');
     
        $scope.foo = ['bar', 'baz'];
     
        locker.get('foo'); // = ['bar', 'baz']
     
    }]);

    You can also set a default value via the third parameter:

    app.controller('AppCtrl', ['$scope', function ($scope) {
     
        locker.bind($scope, 'foo', 'someDefault');
     
        $scope.foo; // = 'someDefault'
     
        locker.get('foo'); // = 'someDefault'
     
    }]);

    To unbind the $scope property, simply use the unbind method:

    app.controller('AppCtrl', ['$scope', function ($scope) {
     
        locker.unbind($scope, 'foo');
     
        $scope.foo; // = undefined
     
        locker.get('foo'); // = undefined
     
    }]);

    Browser Compatibility

    IE8 is not supported because I am utilising Object.keys()

    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

    Contributing

    Take care to maintain the existing coding style using the provided .jscsrc file. Add unit tests for any new or changed functionality. Lint and test your code using Gulp.

    Development

    $ npm install
    $ gulp

    License

    The MIT License (MIT)

    Copyright (c) 2014 Sean Tymon

    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.

    Install

    npm i angular-locker

    DownloadsWeekly Downloads

    855

    Version

    2.0.5

    License

    MIT

    Last publish

    Collaborators

    • tymondesigns