angular-locker.js

/**
 * angular-locker
 *
 * A simple & configurable abstraction for local/session storage in angular projects.
 *
 * @link https://github.com/tymondesigns/angular-locker
 * @author Sean Tymon @tymondesigns
 * @license MIT License, http://www.opensource.org/licenses/MIT
 */

(function (root, factory) {
    if (typeof define === 'function' && define.amd) {
        define(function () {
            return factory(root.angular || (window && window.angular));
        });
    } else if (typeof exports === 'object') {
        module.exports = factory(root.angular || (window && window.angular));
    } else {
        factory(root.angular);
    }
})(this, function (angular) {

    'use strict';

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

    .provider('locker', function () {

        /**
         * If value is a function then execute, otherwise return
         *
         * @private
         *
         * @param  {Mixed}  value  The value to execute or return
         * @param  {Mixed}  param  The parameter to pass to function if applicable
         *
         * @return {Mixed}
         */
        var _value = function (value, param) {
            return angular.isFunction(value) ? value(param) : value;
        };

        /**
         * Determine whether a value is defined and not null
         *
         * @private
         *
         * @param  {Mixed}  value  The value to check
         *
         * @return {Boolean}
         */
        var _defined = function (value) {
            return angular.isDefined(value) && value !== null;
        };

        /**
         * Trigger an error
         *
         * @private
         * @throws {Error}
         *
         * @param  {String}  msg  The error message
         */
        var _error = function (msg) {
            throw new Error('[angular-locker] ' + msg);
        };

        /**
         * Set the defaults
         *
         * @private
         *
         * @type {Object}
         */
        var defaults = {
            driver: 'local',
            namespace: 'locker',
            eventsEnabled: true,
            separator: '.',
            extend: {}
        };

        return {

            /**
             * Allow the defaults to be specified via the `lockerProvider`
             *
             * @param {Object}  value  The defaults to override
             */
            defaults: function (value) {
                if (! _defined(value)) return defaults;

                angular.forEach(value, function (val, key) {
                    if (defaults.hasOwnProperty(key)) defaults[key] = val;
                });
            },

            /**
             * The locker service
             */
            $get: ['$window', '$rootScope', '$parse', function ($window, $rootScope, $parse) {

                /**
                 * Define the Locker class
                 *
                 * @public
                 * @constructor
                 *
                 * @param {Object}  options  The config options to initialize with
                 */
                function Locker (options) {

                    /**
                     * The config options
                     *
                     * @private
                     *
                     * @type {Object}
                     */
                    this._options = options;

                    /**
                     * Out of the box drivers
                     *
                     * @private
                     *
                     * @type {Object}
                     */
                    this._registeredDrivers = angular.extend({
                        local: $window.localStorage,
                        session: $window.sessionStorage
                    }, options.extend);

                    /**
                     * Get the Storage instance from the key
                     *
                     * @private
                     *
                     * @param  {String}  driver  The storage driver identifier
                     *
                     * @return {Storage}
                     */
                    this._resolveDriver = function (driver) {
                        if (! this._registeredDrivers.hasOwnProperty(driver)) {
                            _error('The driver "' + driver + '" was not found.');
                        }

                        return this._registeredDrivers[driver];
                    };

                    /**
                     * The driver instance
                     *
                     * @private
                     *
                     * @type {Storage}
                     */
                    this._driver = this._resolveDriver(options.driver);

                    /**
                     * The namespace value
                     *
                     * @private
                     *
                     * @type {String}
                     */
                    this._namespace = options.namespace;

                    /**
                     * Separates the namespace from the keys
                     *
                     * @private
                     *
                     * @type {String}
                     */
                    this._separator = options.separator;

                    /**
                     * Store the watchers here so we can un-register them later
                     *
                     * @private
                     *
                     * @type {Object}
                     */
                    this._watchers = {};

                    /**
                     * Check browser support
                     *
                     * @private
                     * @see github.com/Modernizr/Modernizr/blob/master/feature-detects/storage/localstorage.js#L38-L47
                     *
                     * @param  {String}  driver  The driver to check support with
                     *
                     * @return {Boolean}
                     */
                    this._checkSupport = function (driver) {
                        if (! _defined(this._supported)) {
                            var l = 'l';
                            try {
                                this._resolveDriver(driver || options.driver).setItem(l, l);
                                this._resolveDriver(driver || options.driver).removeItem(l);
                                this._supported = true;
                            } catch (e) {
                                this._supported = false;
                            }
                        }

                        return this._supported;
                    };

                    /**
                     * Build the storage key from the namspace
                     *
                     * @private
                     *
                     * @param  {String}  key  The key to build the prefix with
                     *
                     * @return {String}
                     */
                    this._getPrefix = function (key) {
                        if (! this._namespace) return key;

                        return this._namespace + this._separator + key;
                    };

                    /**
                     * Try to encode value as json, or just return the value upon failure
                     *
                     * @private
                     *
                     * @param  {Mixed}  value  The value to serialize
                     *
                     * @return {Mixed}
                     */
                    this._serialize = function (value) {
                        try {
                            return angular.toJson(value);
                        } catch (e) {
                            return value;
                        }
                    };

                    /**
                     * Try to parse value as json, if it fails then it probably isn't json
                     * so just return it
                     *
                     * @private
                     *
                     * @param  {String}  value  The value to unserialize
                     *
                     * @return {Mixed}
                     */
                    this._unserialize = function (value) {
                        try {
                            return angular.fromJson(value);
                        } catch (e) {
                            return value;
                        }
                    };

                    /**
                     * Trigger an event
                     *
                     * @private
                     *
                     * @param  {String}  name     The name of the event to trigger
                     * @param  {Object}  payload  The data to pass along with event
                     */
                    this._event = function (name, payload) {
                        if (this._options.eventsEnabled) {
                            $rootScope.$emit('locker.' + name, angular.extend(payload, {
                                driver: this._options.driver,
                                namespace: this._namespace,
                            }));
                        }
                    };

                    /**
                     * Add to storage
                     *
                     * @private
                     * @throws {Error}   if browser support fails
                     *
                     * @param  {String}  key    The key to add
                     * @param  {Mixed}   value  The value to add
                     */
                    this._setItem = function (key, value) {
                        if (! this._checkSupport()) {
                            _error('The browser does not support the "' + options.driver + '" driver');
                        }

                        try {
                            var oldVal = this._getItem(key);
                            this._driver.setItem(this._getPrefix(key), this._serialize(value));
                            if (this._exists(key) && ! angular.equals(oldVal, value)) {
                                this._event('item.updated', { key: key, oldValue: oldVal, newValue: value });
                            } else {
                                this._event('item.added', { key: key, value: value });
                            }
                        } catch (e) {
                            if (['QUOTA_EXCEEDED_ERR',
                                'NS_ERROR_DOM_QUOTA_REACHED',
                                'QuotaExceededError'].indexOf(e.name) !== -1) {
                                _error('The browser storage quota has been exceeded');
                            } else {
                                _error('Could not add item with key "' + key + '"');
                            }
                        }
                    };

                    /**
                     * Get from storage
                     *
                     * @private
                     * @throws {Error}   if browser support fails
                     *
                     * @param  {String}  key  The key to get
                     *
                     * @return {Mixed}
                     */
                    this._getItem = function (key) {
                        if (! this._checkSupport()) {
                            _error('The browser does not support the "' + options.driver + '" driver');
                        }

                        return this._unserialize(this._driver.getItem(this._getPrefix(key)));
                    };

                    /**
                     * Exists in storage
                     *
                     * @private
                     * @throws {Error}   if browser support fails
                     *
                     * @param  {String}  key  The key to check for existence
                     *
                     * @return {Boolean}
                     */
                    this._exists = function (key) {
                        if (! this._checkSupport()) {
                            _error('The browser does not support the "' + options.driver + '" driver');
                        }

                        return this._driver.hasOwnProperty(this._getPrefix(_value(key))) || !! this._getItem(key);
                    };

                    /**
                     * Remove from storage
                     *
                     * @private
                     * @throws {Error}   if browser support fails
                     *
                     * @param  {String}  key  The key to remove
                     *
                     * @return {Boolean}
                     */
                    this._removeItem = function (key) {
                        if (! this._checkSupport()) {
                            _error('The browser does not support the "' + options.driver + '" driver');
                        }

                        if (! this._exists(key)) return false;

                        this._driver.removeItem(this._getPrefix(key));
                        this._event('item.forgotten', { key: key });

                        return true;
                    };
                }

                /**
                 * Define the public api
                 *
                 * @public
                 *
                 * @type {Object}
                 */
                Locker.prototype = {

                    /**
                     * Add a new item to storage (even if it already exists)
                     *
                     * @public
                     *
                     * @param  {Mixed}  key    The key to add
                     * @param  {Mixed}  value  The value to add
                     * @param  {Mixed}  def    The default to pass to function if doesn't already exist
                     *
                     * @return {Locker|Boolean}
                     */
                    put: function (key, value, def) {
                        if (! _defined(key)) return false;
                        key = _value(key);

                        if (angular.isObject(key)) {
                            angular.forEach(key, function (value, key) {
                                this._setItem(key, _defined(value) ? value : def);
                            }, this);
                        } else {
                            if (! _defined(value)) return false;
                            var val = this._getItem(key);
                            this._setItem(key, _value(value, _defined(val) ? val : def));
                        }

                        return this;
                    },

                    /**
                     * Add an item to storage if it doesn't already exist
                     *
                     * @public
                     *
                     * @param  {Mixed}  key    The key to add
                     * @param  {Mixed}  value  The value to add
                     * @param  {Mixed}  def    The default to pass to function if doesn't already exist
                     *
                     * @return {Boolean}
                     */
                    add: function (key, value, def) {
                        if (! this.has(key)) {
                            this.put(key, value, def);
                            return true;
                        }

                        return false;
                    },

                    /**
                     * Retrieve the specified item from storage
                     *
                     * @public
                     *
                     * @param  {String|Array}  key  The key to get
                     * @param  {Mixed}         def  The default value if it does not exist
                     *
                     * @return {Mixed}
                     */
                    get: function (key, def) {
                        if (angular.isArray(key)) {
                            var items = {};
                            angular.forEach(key, function (k) {
                                if (this.has(k)) items[k] = this._getItem(k);
                            }, this);

                            return items;
                        }

                        if (! this.has(key)) return arguments.length === 2 ? def : void 0;

                        return this._getItem(key);
                    },

                    /**
                     * Determine whether the item exists in storage
                     *
                     * @public
                     *
                     * @param  {String|Function}  key  -  The key to remove
                     *
                     * @return {Boolean}
                     */
                    has: function (key) {
                        return this._exists(key);
                    },

                    /**
                     * Remove specified item(s) from storage
                     *
                     * @public
                     *
                     * @param  {String|Array}  key  The key or array of keys to remove
                     *
                     * @return {Object}
                     */
                    forget: function (key) {
                        key = _value(key);

                        if (angular.isArray(key)) {
                            key.map(this._removeItem, this);
                        } else {
                            this._removeItem(key);
                        }

                        return this;
                    },

                    /**
                     * Retrieve the specified item from storage and then remove it
                     *
                     * @public
                     *
                     * @param  {String|Array}  key  The key to pull from storage
                     * @param  {Mixed}         def  The default value if it does not exist
                     *
                     * @return {Mixed}
                     */
                    pull: function (key, def) {
                        var value = this.get(key, def);
                        this.forget(key);

                        return value;
                    },

                    /**
                     * Return all items in storage within the current namespace/driver
                     *
                     * @public
                     *
                     * @return {Object}
                     */
                    all: function () {
                        var items = {};
                        angular.forEach(this._driver, function (value, key) {
                            if (this._namespace) {
                                var prefix = this._namespace + this._separator;
                                if (key.indexOf(prefix) === 0) key = key.substring(prefix.length);
                            }
                            if (this.has(key)) items[key] = this.get(key);
                        }, this);

                        return items;
                    },

                    /**
                     * Get the storage keys as an array
                     *
                     * @public
                     *
                     * @return {Array}
                     */
                    keys: function () {
                        return Object.keys(this.all());
                    },

                    /**
                     * Remove all items set within the current namespace/driver
                     *
                     * @public
                     *
                     * @return {Locker}
                     */
                    clean: function () {
                        return this.forget(this.keys());
                    },

                    /**
                     * Empty the current storage driver completely. careful now.
                     *
                     * @public
                     *
                     * @return {Locker}
                     */
                    empty: function () {
                        this._driver.clear();

                        return this;
                    },

                    /**
                     * Get the total number of items within the current namespace
                     *
                     * @public
                     *
                     * @return {Integer}
                     */
                    count: function () {
                        return this.keys().length;
                    },

                    /**
                     * Bind a storage key to a $scope property
                     *
                     * @public
                     *
                     * @param  {Object}  $scope  The angular $scope object
                     * @param  {String}  key     The key in storage to bind to
                     * @param  {Mixed}   def     The default value to initially bind
                     *
                     * @return {Locker}
                     */
                    bind: function ($scope, key, def) {
                        if (! _defined( $scope.$eval(key) )) {
                            $parse(key).assign($scope, this.get(key, def));
                            this.add(key, def);
                        }

                        var self = this;
                        this._watchers[key + $scope.$id] = $scope.$watch(key, function (newVal) {
                            self.put(key, newVal);
                        }, angular.isObject($scope[key]));

                        return this;
                    },

                    /**
                     * Unbind a storage key from a $scope property
                     *
                     * @public
                     *
                     * @param  {Object}  $scope  The angular $scope object
                     * @param  {String}  key     The key to remove from bindings
                     *
                     * @return {Locker}
                     */
                    unbind: function ($scope, key) {
                        $parse(key).assign($scope, void 0);
                        this.forget(key);

                        var watchId = key + $scope.$id;

                        if (this._watchers[watchId]) {
                            // execute the de-registration function
                            this._watchers[watchId]();
                            delete this._watchers[watchId];
                        }

                        return this;
                    },

                    /**
                     * Set the storage driver on a new instance to enable overriding defaults
                     *
                     * @public
                     *
                     * @param  {String}  driver  The driver to switch to
                     *
                     * @return {Locker}
                     */
                    driver: function (driver) {
                        return this.instance(angular.extend(this._options, { driver: driver }));
                    },

                    /**
                     * Get the currently set driver
                     *
                     * @public
                     *
                     * @return {Storage}
                     */
                    getDriver: function () {
                        return this._driver;
                    },

                    /**
                     * Set the namespace on a new instance to enable overriding defaults
                     *
                     * @public
                     *
                     * @param  {String}  namespace  The namespace to switch to
                     *
                     * @return {Locker}
                     */
                    namespace: function (namespace) {
                        return this.instance(angular.extend(this._options, { namespace: namespace }));
                    },

                    /**
                     * Get the currently set namespace
                     *
                     * @public
                     *
                     * @return {String}
                     */
                    getNamespace: function () {
                        return this._namespace;
                    },

                    /**
                     * Check browser support
                     *
                     * @public
                     * @see github.com/Modernizr/Modernizr/blob/master/feature-detects/storage/localstorage.js#L38-L47
                     *
                     * @param  {String}  driver  The driver to check support with
                     *
                     * @return {Boolean}
                     */
                    supported: function (driver) {
                        return this._checkSupport(driver);
                    },

                    /**
                     * Get a new instance of Locker
                     *
                     * @public
                     *
                     * @param  {Object}  options  The config options to instantiate with
                     *
                     * @return {Locker}
                     */
                    instance: function (options) {
                        return new Locker(options);
                    }
                };

                // return the default instance
                return new Locker(defaults);
            }]
        };

    }).name; // export module name for the likes of Browserify and Webpack

});