Cookies.js (XTREME VERSION!!!)

Cookies.js (XTREME VERSION!!!) is a small client-side javascript library that makes managing cookies easy. It is a fork of the super rad library Cookies.js. The purpose of this library is to make Cookies.js event driven so you can monitor changes to cookies.

Features
Browser Compatibility
Getting the Library
Use in CommonJS/Node Environments Without window
A Note About Encoding
API Reference

Features

• RFC6265 compliant
• Cross browser
• Lightweight
• No dependencies
• Public domain
• Supports AMD / CommonJS loaders

Browser Compatibility

The following browsers have passed all of the automated Cookies.js tests:

• Chrome
• Firefox 3+
• Safari 4+
• Opera 10+
• Internet Explorer 6+

Getting the Library

Direct downloads

• v1.0.0 Minified (~1 KB gzipped)
• v1.0.0 Unminified (~1.7 KB gzipped)

Node Package Manager

npm install cookies-xtreme

YARN!!!!

yarn install cookies-xtreme

Use in CommonJS/Node Environments Without window

In environments where there is no native window object, Cookies.js will export a factory method that accepts a window instance. For example, using jsdom, you might do something like:

var jsdom = require('jsdom');
var window = jsdom.jsdom().parentWindow;
var Cookies = require('cookies-xtreme')(window);

// Use Cookies as you normally would

A Note About Encoding

RFC6265 defines a strict set of allowed characters for cookie keys and values. In order to effectively allow any character to be used in a key or value, Cookies.js will URI encode disallowed characters in their UTF-8 representation. As such, Cookies.js also expects cookie keys and values to already be URI encoded in a UTF-8 representation when it accesses cookies. Keep this in mind when working with cookies on the server side.

.NET Users

Do not use HttpUtility.UrlEncode and HttpUtility.UrlDecode on cookie keys or values. HttpUtility.UrlEncode will improperly escape space characters to '+' and lower case every escape sequence. HttpUtility.UrlDecode will improperly unescape every '+' to a space character. Instead, use System.Uri.EscapeDataString and System.Uri.UnescapeDataString.

API Reference

Methods
Cookies.set(key, value [, options])
Cookies.get(key)
Cookies.expire(key [, options])
Cookies.addListener(key, listener)
Cookies.removeListener(key, listener)
Cookies.removeAllListeners(key)
Cookies.emit(key, data)

Properties
Cookies.enabled
Cookies.defaults

Methods

Cookies.set(key, value [, options])

Alias: Cookies(key, value [, options])

Sets a cookie in the document. If the cookie does not already exist, it will be created. Returns the Cookies object.

| Option | Description | Default | | --------: | ------------------------------------------------------------------------------------------------ | ----------- | | path | A string value of the path of the cookie | "/" | | domain | A string value of the domain of the cookie | undefined | | expires | A number (of seconds), a date parsable string, or a Date object of when the cookie will expire | undefined | | secure | A boolean value of whether or not the cookie should only be available over SSL | false |

A default value for any option may be set in the Cookies.defaults object.

Example Usage

// Setting a cookie value
Cookies.set('key', 'value');

// Chaining sets together
Cookies.set('key', 'value').set('hello', 'world');

// Setting cookies with additional options
Cookies.set('key', 'value', { domain: 'www.example.com', secure: true });

// Setting cookies with expiration values
Cookies.set('key', 'value', { expires: 600 }); // Expires in 10 minutes
Cookies.set('key', 'value', { expires: '01/01/2012' });
Cookies.set('key', 'value', { expires: new Date(2012, 0, 1) });
Cookies.set('key', 'value', { expires: Infinity });

// Using the alias
Cookies('key', 'value', { secure: true });

Cookies.get(key)

Alias: Cookies(key)

Returns the value of the most locally scoped cookie with the specified key.

Example Usage

// First set a cookie
Cookies.set('key', 'value');

// Get the cookie value
Cookies.get('key'); // "value"

// Using the alias
Cookies('key'); // "value"

Cookies.expire(key [, options])

Alias: Cookies(key, undefined [, options])

Expires a cookie, removing it from the document. Returns the Cookies object.

| Option | Description | Default | | --------: | ------------------------------------------------------------------------------------------------ | ----------- | | path | A string value of the path of the cookie | "/" | | domain | A string value of the domain of the cookie | undefined |

A default value for any option may be set in the Cookies.defaults object.

Example Usage

// First set a cookie and get its value
Cookies.set('key', 'value').get('key'); // "value"

// Expire the cookie and try to get its value
Cookies.expire('key').get('key'); // undefined

// Using the alias
Cookies('key', undefined);

Cookies.addListener(key, listener)

Adds a listener for the given key. When a cookie value is set, an event of the form set.key - where key is the cookie key - will be emitted.

Example Usage

Cookies.addListener('set.key', function(value) {
  // do something with value
});

Cookies.removeListener(key, listener)

Removes a listener for the given key.

Example Usage

var listener = function(data) {
  // do something with data
};

Cookies.addListener('set.key', listener);

// do a bunch of things that trigger the listener

// clean up when done
Cookies.removeListener('set.key', listener);

Cookies.removeAllListeners(key)

Removes all listeners for the given key

Example Usage

Cookies.removeAllListeners('set.key');

Cookies.emit(key, data)

Trigger an event for the given key. This is best reserved for internal use. All calls to Cookies.set or it's alias will result in an event of set.key - where key is the cookie key.

Example Usage

Cookies.addListener('set.key', function (cookieValue) {
  var result = cookieValue; // will be "my cookie value" in this instance
});

Cookies.emit('set.key', 'my cookie value');

Properties

Cookies.enabled

A boolean value of whether or not the browser has cookies enabled.

Example Usage

if (Cookies.enabled) {
    Cookies.set('key', 'value');
}

Cookies.defaults

An object representing default options to be used when setting and expiring cookie values.

| Option | Description | Default | | --------: | ------------------------------------------------------------------------------------------------ | ----------- | | path | A string value of the path of the cookie | "/" | | domain | A string value of the domain of the cookie | undefined | | expires | A number (of seconds), a date parsable string, or a Date object of when the cookie will expire | undefined | | secure | A boolean value of whether or not the cookie should only be available over SSL | false |

Example Usage

Cookies.defaults = {
    path: '/',
    secure: true
};

Cookies.set('key', 'value'); // Will be secure and have a path of '/'
Cookies.expire('key'); // Will expire the cookie with a path of '/'