Cookies.js

Cookies.js is a small client-side javascript library that makes managing cookies easy.

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.2.3 Minified (~1 KB gzipped)
- v1.2.3 Unminified (~1.7 KB gzipped)

#### Node Package Manager
npm install cookies-js

#### Bower
bower install cookies-js

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:

``javascript
var jsdom = require('jsdom');
var window = jsdom.jsdom().parentWindow;
var Cookies = require('cookies-js')(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])](#cookiessetkey-value--options)
Cookies.get(key)
[Cookies.expire(key [, options])](#cookiesexpirekey--options)

Properties
Cookies.enabled
Cookies.defaults

$3

#### 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
`javascript
// 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
`javascript
// 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
`javascript
// 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);
`

$3

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

Example Usage
`javascript
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
`javascript
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 '/'
``