Cookie Handler and manager

cookie.js

/**
 * Javascript cookie handler
 *
 * Brings you a Cookie class and a global cookie handler that's ease cookies
 * management.
 *
 * @author      Evandro Oliveira http://github.com/oliveiraev
 * @version     0.1 alpha
 * @license     http://www.opensource.org/licenses/mit-license.php
 * @link        https://gist.github.com/1229529
 *
 * 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.
 */

(function () {
    var

        /**
         * A set of cookies stored. Persisted or not.
         */
        $_cookies = {},

        /**
         * Default values for empty cookie constructor.
         */
        $_defaults  = {
            'value'     : null,
            'days'      : 30,
            'hours'     : 0,
            'minutes'   : 0,
            'seconds'   : 0,
            'path'      : '/'
        },

        /**
         * The cookie class
         *
         * Instances of cookies describes the cookie value, validity and path.
         * Cookie name is defined through the persist() method. Cookie instances
         * let you easily change the cookie expiration date and path. Of course,
         * you need to "save" the new options with the persist() method.
         *
         * @param $value String: A value to be stored inside the Cookie object.
         * @param $validity Date: The date of validity of the cookie. If not
         * set, the validity date is calculated between 'now' and the default
         * values passed within $defaults.
         * @param $path String: A path on the domain that the cookie is
         * readable.
         * @return Cookie: A new cookie instance.
         */
        Cookie = function ($value, $validity, $path) {
            var

                /**
                 * Cookie info.
                 */
                $_params = {},

                /**
                 * Date instance to build default cookie validity
                 */
                $_date   = new Date(),

                /**
                 * Evaluations for default cookie validity
                 */
                $_diff   = $_defaults.seconds
                + $_defaults.minutes * 60
                + $_defaults.hours * 3600
                + $_defaults.days * 86400,

                /**
                 * Private method that verifies if $_autosave is on and persist
                 * the cookie.
                 */
                $_save   = function () {
                    if ($_params.autosave) {
                        this.persist($_params.name);
                    }
                };

            /**
             * Changes the value of Cookie
             *
             * To send the new value to the server, Cookie must be "persisted"
             * with persist() method.
             *
             * @param $newValue String: The new value of current Cookie.
             */
            this.setValue       = function ($newValue) {
                $_params.value  = $newValue;
                $_save();
            };

            /**
             * Updates the validity of current cookie
             *
             * Changes expiration date of the cookie when persist() method is
             * called. Can also be used to delete the refered cookie, although
             * the use of cookie.remove() method is more encouraged and easy.
             *
             * @param $newValidity Date: A date object - in the past or future -
             * to be used on the persist() action.
             */
            this.setValidity    = function ($newValidity) {
                if (!($newValidity instanceof Date)) {
                    throw new Error(
                        '$newValidity argument must be an instance of Date.'
                    );
                }
                $_params.validity = $newValidity.toGMTString();
                $_save();
            };

            /**
             * Alter the path visibility
             *
             * Define the path that cookie will be accessible. As usual, value
             * must be saved with persist() call.
             *
             * @param $newPath String: The new access path.
             */
            this.setPath        = function ($newPath) {
                $_params.path   = $newPath;
                $_save();
            };

            /**
             * Modify the autosave behaviour
             *
             * Choose either persist every change made to current instance into
             * a defined cookie name.
             */
            this.autosave       = function ($switch, $name) {
                $_params.autosave = !!$switch;
                if ($switch) {
                    if (undefined === $name) {
                        throw new Error('Required $name not set.');
                    }
                    $_params.name = $name;
                }
            };

            /**
             * Takes the cookie stored value
             *
             * @return String
             */
            this.getValue       = function () {
                return $_params.value;
            };

            /**
             * Perform a cookie definition
             *
             * This method specifies that you confirm the cookie stored data
             * and "save" them on a real browser cookie. After persist() call,
             * new server requests can be made with the cookie value being sent
             * together. When $_autosave is TRUE, this method is called at each
             * change on data.
             *
             * @param $into String: A name to identify the cookie value.
             */
            this.persist        = function ($into) {
                if (undefined === $into) {
                    throw new Error('Cookie name must be specified.');
                }
                document.cookie = $into + '=' + $_params.value
                    + '; expires=' + $_params.validity
                    + '; path='    + $_params.path;
            };

            /**
             * Constructor method.
             */
            (function ($cookie) {
                $cookie.setValue(
                    undefined === $value ? $_defaults.value : $value
                );
                if (!($validity instanceof Date)) {
                    $validity = new Date($_date.getTime() + $_diff * 1000);
                }
                $cookie.setValidity($validity);
                $cookie.setPath(undefined === $path ? $_defaults.path : $path);
            }(this));
            return this;
        };

    window.Cookie = Cookie;

    /**
     * Refreshes the cookies table.
     */
    function $_update() {
        var
            $i = 0,
            $cookVal = null,
            $cookList = document.cookie.split('; '),
            $ln = $cookList.length;
        $_cookies = {};
        for ($cookVal = $cookList[$i].split('='); $i < $ln; $i++) {
            $_cookies[$cookVal[0]] = new Cookie($cookVal[1]);
        }
    }

    /**
     * Retrieve a fetched cookie
     *
     * Search for cookies inside the window.cookie list. It will not re-parse the
     * stored browser cookies. If cookie object was individually saved with
     * persist() method instead of set() method. The last persists the cookie
     * and automatically refresh the window.cookie table.
     *
     * @param $cookieName String: Identification of the stored cookie.
     * @return Cookie|null: The found cookie or null if $cookieName is not
     * valid.
     */
    window.Cookie.get    = function ($cookieName) {
        return $_cookies[$cookieName];
    };

    /**
     * Carves the cookie
     *
     * This method sets the cookie on the browser and refresh the cookie table
     * to be fetchable with get() method.
     *
     * @param $cookieName String:
     * @param $cookie Cookie:
     */
    window.Cookie.set    = function ($cookieName, $cookie) {
        if (!($cookie instanceof Cookie)) {
            throw new Error('$cookie must be an instance of Cookie.');
        }
        $cookie.persist($cookieName);
        $_update();
    };

    /**
     * Wipe a cookie
     *
     * Unset the cookie on the browser and also clear it from the cookie table.
     * A call of get($cookieName) will now return undefined.
     *
     * @param $cookieName String: Identification of the cookie
     */
    window.Cookie.remove = function ($cookieName) {
        var $cookie = this.get($cookieName);
        if ($cookie) {
            $cookie.setValidity(new Date());
            $cookie.persist($cookieName);
        }
        $_update();
    };

    /**
     * Changes default values
     *
     * This method let alter default values that will be passed to a new
     * cookie instance created by cookie() method.
     *
     * @param $values Object: A pair of property: value variables that defines
     * default cookie values. Possible property values are: seconds (int),
     * minutes (int), hours (int), days (int), path (string). Default values
     * are: seconds: 0, minutes: 0, hours: 0, days: 30, path: '/' that means a
     * default cookie will be set into '/' path, with validity of 30 days.
     */
    window.Cookie.defaults = function ($values) {
        var $i = null, $val = {};
        for ($i in $values) {
            if (undefined !== $_defaults[$i]) {
                $val = $values[$i];
                switch ($i) {
                case 'value':
                    $_defaults.value    = $val;
                    break;

                case 'seconds':
                    $_defaults.seconds  = parseInt($val, 10);
                    break;

                case 'minutes':
                    $_defaults.minutes  = parseInt($val, 10);
                    break;

                case 'hours':
                    $_defaults.hours    = parseInt($val, 10);
                    break;

                case 'days':
                    $_defaults.days     = parseInt($val, 10);
                    break;

                case 'path':
                    $_defaults.path     = $val;
                    break;

                default:
                }
            }
        }
    };
    $_update();
}());