Cookie Storage

A lightweight JavaScript UMD to handle cookies through Web Storage Interface.

This library manages an adapter that implements an interface similar to Web Storage to normalize the API for document.cookie to be as localStorage / sessionStorage, with the advantage that values are stored as JSON, allowing to store and retrieve values of type: Object and Array<Any> (not possible when using the native document.cookie API).

If you want a more robust mechanism to store data in cookies, localStorage, sessionStorage, or memoryStorage, you should try the proxy-storage library.

Installing the library

To include this library into your package manager with npm or yarn, run:

# with npm
$ npm install cookie-storage-v2 --save

# with yarn
$ yarn add cookie-storage-v2

Including the library

cookie-storage can be included directly from a CDN in your page:

<!-- from unpkg.com -->
<script src="https://unpkg.com/cookie-storage-v2/dist/cookie-storage.min.js"></script>

<!-- or from rawgit.com -->
<script src="https://cdn.rawgit.com/jherax/cookie-storage/1.1.0/dist/cookie-storage.min.js"></script>

In the above case, cookieStorage is included as a global object in the browser, and you can use it as shown in the API.

Browser

var session = cookieStorage.getItem('sessionId');
cookieStorage.setItem('sessionId', btoa(session));

As cookie-storage is built as UMD (Universal Module Definition), it can be included from module loaders such as CommonJS, ES2015 Imports or AMD RequireJS.

CommonJS

var cookieStorage = require('cookie-storage-v2');

ES2015 Imports

import cookieStorage from 'cookie-storage-v2';

AMD

// using RequireJS
requirejs.config({
  paths: {
    // remove the extension .js
    'cookie-storage': '<PATH>/cookie-storage.min'
  }
});
require(['cookie-storage'], function(cookieStorage) {
  cookieStorage.setItem('testing', [1,2,3,5,8,13], {
    expires: { minutes: 10 },
  });
});

See an example with RequireJS here: http://jsfiddle.net/FdKTn/76/

☗ Back to Index

API

The exposed cookieStorage object is an instance of the internal CookieStorage class, which implements an API similar to the Web Storage interface. It can store and retrieve primitive, Object and Array<Any> values, thanks to JSON.stringify.

The prototype members are:

setItem(key, value, options): stores a value given a key name.
The options parameter is optional and describes the metadata passed to the cookie.
getItem(key): retrieves a value by its key name.
removeItem(key, options): deletes an item from the storage.
The options parameter is optional and describes the metadata passed to the cookie.
clear(): removes all items from the storage instance.
length: gets the number of items stored in the instance.

The parameter options for setItem() and removeItem() is an object that configures the way how the cookie is stored. It has the following properties:

domain{string}: the domain or subdomain where the cookie will be valid.
path{string}: relative path where the cookie is valid. Default "/"
secure{boolean}: if provided, creates a secure cookie over HTTPS.
expires{Date, object}: the expiration date of the cookie. You can pass an object describing the expiration:
- date{Date}: if provided, this date will be applied, otherwise the current date is used.
- minutes{number}: minutes to add / subtract
- hours{number}: hours to add / subtract
- days{number}: days to add / subtract
- months{number}: months to add / subtract
- years{number}: years to add / subtract

Example

import cookieStorage from 'cookie-storage-v2';

let data = {
  start: new Date().toISOString(),
  sessionId: 'J34H5609-SG7ND98W3',
  platform: 'Linux x86_64',
};

cookieStorage.setItem('activity', data, {
  expires: { minutes: 30 },
});

cookieStorage.setItem('testing1', true, {
  secure: true,
  path: '/jherax',
  expires: new Date('2017/12/31'),
});

cookieStorage.setItem('testing2', [1,4,7], {
  domain: '.github.com',
  expires: { days: 1 },
});

cookieStorage.setItem('testing3', 3, {
  expires: {
    date: new Date('2018/03/06'),
    hours: -6,
  },
});

Important: Take into account that if you want to modify or remove a cookie that was created under specific path or domain (subdomain), you need to specify the domain or path attributes in the options parameter when calling setItem(key, value, options) or removeItem(key, options).

If you have created the cookie with cookieStorage, it will handle the metadata internally, so that you can call removeItem(key) with no more arguments. Otherwise you will need to provide the metadata path or domain:

// change the value of an external cookie in /answers
cookieStorage.setItem('landedAnswers', 999, {
  path: '/answers',
});

// remove an external cookie in a subdomain
cookieStorage.removeItem('optimizelyEndUserId', {
  domain: '.healthcare.org',
});

Looping the storage

You can loop over the items in the storage instance, but it is not recommended to rely on it because navigable items in the storage instance are not synchronized with external changes, for example, a cookie has expired, or a cookie/localStorage element was created/deleted from another page with the same domain/subdomain.

cookieStorage.setItem('test1', 1);
cookieStorage.setItem('test2', 2);

// loop over the storage object (not recommended)
Object.keys(cookieStorage).forEach((key) => {
  console.log(key, cookieStorage[key]);
});

// or this way (not recommended either)
for (let key in cookieStorage) {
  console.log(key, cookieStorage[key]);
}

It is also applied not only when reading, but also when writing to storage:

// not recommended: not synchronized with the real storage
var title = cookieStorage['title'];
var session = cookieStorage.sessionId;
cookieStorage['sessionId'] = 'E6URTG5';

// good practice: it is synchronized for external changes
var title = cookieStorage.getItem('title');
var session = cookieStorage.getItem('sessionId');
cookieStorage.setItem('sessionId', 'E6URTG5');

☗ Back to API

Polyfills

This library is written using some of the new ES5/ES6 features. If you have to support Non-standard-compliant browsers like Internet Explorer, you can polyfill some of the missing features with the following alternatives:

Using es6-shim

<!-- put this script FIRST, before all other scripts -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/es6-shim/0.35.3/es6-shim.min.js"></script>

Using polyfill.io

<!-- put this script FIRST, before all other scripts -->
<script src="https://cdn.polyfill.io/v2/polyfill.min.js?features=default-3.3"></script>

Polyfill.io reads the User-Agent header of each request and returns the polyfills that are suitable for the requesting browser.

If you want to request specific polyfills, you can pass a query parameter to the url, for example:

<!--[if IE]>
<script src="https://polyfill.io/v2/polyfill.min.js?features=default-3.3&flags=always"></script>
<![endif]-->

Read the list of available features: Features and Browsers Supported.

☗ Back to Index

Versioning

This projects adopts the Semantic Versioning (SemVer) guidelines:

<MAJOR>.<MINOR>.<PATCH>

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes.
MINOR version when you add functionality in a backwards-compatible manner.
PATCH version when you make backwards-compatible bug fixes.

☗ Back to Index

Issues

To report an issue and keep traceability of bug-fixes, please report to:

https://github.com/jherax/cookie-storage/issues

Changelog

The change history for each version is documented here.

License

This project is released under the MIT license. This license applies ONLY to the source of this repository and doesn't extend to any other distribution, or any other 3rd party libraries used in a repository. See LICENSE file for more information.