browser-cookies

browser-cookies

Tiny cookies library for the browser - under development

Features:

• Clean and easy to use API
• Small footprint (minified and gzipped ~ 0.5kB)
• No dependencies
• RFC6265 compliant
• Cross browser support
• Unit tests
• Supports CommonJS (e.g. Browserify)

Browser compatibility

Cross browser support is verified on real browsers using automated testing:

Installation

// TODO - probably add to NPM

Usage

var cookies = require('browser-cookies');

cookies.set('firstName', 'Lisa');
cookies.set('firstName', 'Lisa', {expires: 365}); // Expires after 1 year
cookies.set('firstName', 'Lisa', {secure: true, domain: 'www.example.org'});

cookies.get('firstName'); // Returns cookie value (or null)

cookies.erase('firstName'); // Removes cookie

More examples

API

cookies.set( name, value [, options] )

Method to save a cookie

• name: (string) the name of the cookie to save
• value: (string) the value to save
• options: (object) may contain any of the properties specified in options below. If an option is not specified, the value configured in cookies.defaults will be used.

cookies.get( name )

Method that returns a cookie value, or null if the cookie is not found

• name: (string) the name of the cookie to retrieve

cookies.erase( name [, options] )

Method to remove a cookie

• name: (string) the name of the cookie to remove
• options: (object) may contain the domain and path properties specified in options below. If an option is not specified, the value configured in cookies.defaults will be used.

cookies.defaults

This object may be used to change the default value of each option specified in options below.

Options

Options may be set globally using cookies.defaults or passed as function argument, see the Examples section below and the API reference above for details.

Name	Type	Default	Description
expires	Number or Date	0	Number of days until the cookie expires, if set to 0 the cookie will expire at the end of the session. Alternatively a Date object may be passed (e.g. new Date(2018, 3, 27) ).
domain	String	""	The domain from where the cookie is readable. If not specified, the current domain will be used.
path	String	"/"	The path from where the cookie is readable, the default value of "/" allows the cookie to be readable from each path. Note that the path must be absolute, cookies don't support relative paths.
secure	Boolean	false	If true the cookie will only be transmitted over secure protocols like https.
httponly	Boolean	false	If true the cookie may only be read by the web server. This option may be set to prevent malicious scripts from accessing cookies, though not all browsers support this feature yet.

Examples

Count the number of a visits to a page:

var cookies = require('browser-cookies');

// Get cookie value
var visits = cookies.get('count', {expires: 365});
console.log("You've been here " + parseInt(visits) + " times before!");

// Increment the counter and set (or update) the cookie
cookies.set('count', parseInt(visits) + 1);

JSON may be saved by converting the object into a string:

var cookies = require('browser-cookies');

// Store JSON data
var user = {firstName: 'Sofia', lastName: 'Dueñas'};
cookies.set('user', JSON.stringify(user))

// Retrieve JSON data
var userString = cookies.get('user');
var userObject = JSON.parse(userString);
alert('Hi ' + userObject.firstName);

The default value of cookie options may be changed:

var cookies = require('browser-cookies');

// Override defaults
cookies.defaults.secure = true;
cookies.defaults.expires = 7;

// This cookie has the 'secure' option enabled and expires after 7 days
cookies.set('FirstName', 'John')

// This cookie has the 'secure' option enabled and expires after 30 days
cookies.set('LastName', 'Smith', {expires: 30})

Todo's

• Additional tests:
  • More test cases to verify proper encoding/decoding (stubbed and non-stubbed).
  • More bad weather scenarios.
  • Mobile browser testing (Disabled automated testing for mobile browsers because the results varied per run).
  • Manually verify support on old browsers that that still need to be supported (i.e. IE6)?
• Distribution:
  • Generate downloadable minified file for CommonJS?
  • Create builds for other loaders (AMD?) and for use without a loader.
  • Add to NPM and possibly Bower.
• Cross browser consistency:
  • IE sends cookies to all domains, perhaps save cookies to all subdomains by default for consistent behavior amongst all browsers? Would need to investigate whether something like window.location.hostname is cross-browser supported though. Or check how other cookie libs solved this.

Development

This design goal is to provide to smallest possible size (when minified and gzipped) for the given API, while remaining compliant to RFC6265 and providing cross-browser compatibility and consistency.

Development setup (requires node and git to be installed):

git clone https://github.com/voltace/browser-cookies.git
cd browser-cookies
npm install         # Install dev dependencies
npm run test:local  # Run unit tests locally (takes ~5 seconds)
npm run build       # Create minified version

Feel free to add issues on GitHub for questions, bug reports and feature requests.

License

Public Domain (UNLICENSE)