New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More →
Socket
Sign inDemoInstall
Socket
Sign inDemoInstall

crumble

Package Overview
Dependencies
Maintainers
1
Versions
17
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

crumble - npm Package Compare versions

Comparing version

0.2.1
to
0.3.0

16

LICENSE.txt
MIT License
Copyright (c) 2015 Luke Phillips
Copyright (c) 2015 - 2016 Luke Phillips

@@ -9,8 +9,8 @@ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

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.
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.

22

package.json
{
"name" : "crumble",
"version" : "0.2.1",
"description" : "A simple utility that abstracts the legacy API that is document.cookie",
"version" : "0.3.0",
"description" : "A simple wrapper that makes reading the cookies of a given document easy and expressive.",
"author" :
{
"name" : "Luke Phillips",
"email" : "lsphillips.mail@gmail.com",
"url" : "http://www.lsphillips.com"
"email" : "lsphillips.mail@gmail.com"
},

@@ -29,15 +28,10 @@

"directories" :
{
"src" : "src",
"test" : "test"
},
"devDependencies" :
{
"should" : "7.0.1",
"cookie" : "0.2.3",
"chai" : "3.5.0",
"chai-string" : "1.2.0",
"sinon" : "1.15.4",
"grunt" : "0.4.5",
"grunt-contrib-jshint" : "0.11.2",
"grunt-contrib-uglify" : "0.9.1",
"grunt-contrib-jshint" : "0.11.3",
"grunt-mocha-cli" : "1.13.1"

@@ -44,0 +38,0 @@ },

109

README.md

@@ -1,32 +0,52 @@

## Crumble
# Crumble
A simple utility that abstracts the legacy API that is `document.cookie`.
A simple wrapper that makes reading the cookies of a given document easy and expressive.
## Usage
### `Boolean Crumble.isEnabled()`
The Crumble constructor has this signature:
Determines whether the client has cookies enabled.
```
Crumble(HTMLDocument document)
```
### `Boolean Crumble.has(string name)`
Example usage:
Determines if a cookie exists.
```
var cookies = new Crumble(window.document);
### `String Crumble.get(string name)`
if (cookies.isEnabled() === false)
{
window.alert('You do not have cookies enabled.');
}
```
Retrieves the value of a cookie. `null` will be returned if the cookie does not exist.
### Interface
### `void Crumble.set(Object crumbs [, string value])`
#### `Boolean Crumble#isEnabled()`
Sets a cookie.
Determines whether cookies are enabled in the target document.
#### `Boolean Crumble#has(string name)`
Determines whether a cookie exists in the target document.
#### `String Crumble#get(string name)`
Retrieves the value of a cookie from the target document. `null` will be returned if the cookie does not exist.
#### `void Crumble#set(Object crumbs [, string value])`
Sets a cookie in the target document.
The cookie crumbs you can provide are:
* `name` (String, required) - The name of the cookie.
* `value` (String, optional) - The value of the cookie. If set to `undefined` or `null` the cookie will be removed by forcing it to immediately expire, ignoring any `age` or `expires` crumb that may be provided.
* `expires` (Date|String|Number, optional) - The expiry date of the cookie, if omitted, the cookie will expire at the end of the session. You can provide a date object, date string or a timestamp. If provided a timestamp equivalent to `Infinity` the cookie will be set to expire with date: `31 Dec 9999 23:59:59 GMT`.
* `age` (Number, optional) - The duration (in minutes) of which the cookie can live. When defined, any provided expiry date is ignored. If set to `Infinity` the cookie will be set to expire with date: `31 Dec 9999 23:59:59 GMT`.
* `path` (String, optional) - The path of which the cookie will be sent. Defaults to `/`.
* `domain` (String, optional) - The (sub)domain of which the cookie will be sent. The domain can only be a domain that the current document is in, however cookies can cross subdomains. If set to `.` the domain will be set to the root domain of the document. Defaults to the domain of the document (i.e. the value of `document.cookie`).
* `value` (String, optional) - The value of the cookie. When set to `undefined` the cookie will be removed by forcing it to immediately expire, ignoring any `age` or `expires` crumb that may be provided.
* `age` (Number, optional) - The duration (in milliseconds) of which the cookie can live. When defined, any provided expiry date is ignored. When set to `Infinity` the cookie will be set to expire with date: `31 Dec 9999 23:59:59 GMT`.
* `expires` (Date|String|Number, optional) - The expiry date of the cookie, if omitted, the cookie will expire at the end of the session. You can provide a date object, date string or a timestamp. When provided a timestamp equivalent to `Infinity` the cookie will be set to expire with date: `31 Dec 9999 23:59:59 GMT`.
* `path` (String, optional) - The path of which the cookie will be created. Defaults to the path of the target document.
* `domain` (String, optional) - The (sub)domain of which the cookie will be created. The domain can only be a domain that the target document is in, however cookies can cross subdomains. When set to `.` the domain will be set to the root domain of the document. Defaults to the domain of the document (i.e. the value of `document.domain`).
* `secure` (Boolean, optional) - Indicates whether the cookie should only be passed over HTTPS connections. Defaults to `false`.
* `firstPartyOnly` (Boolean, optional) - Indicates whether the cookie should only be sent in a first-party context. This is subject to client support. Defaults to `false`.

@@ -36,21 +56,14 @@ Example usage:

``` js
Crumble.set(
cookies.set(
{
name : 'name',
value : 'value',
domain : 'a.domain.com',
path : '/a/document/path',
secure : false
name : 'name', value : 'value', domain : 'a.domain.com', path : '/a/document/path', secure : false
});
```
Alternatively you can separate the value from the cookie crumbs, like so:
Alternatively you can separate the value from the cookie crumbs:
``` js
Crumble.set(
cookies.set(
{
name : 'name',
domain : 'a.domain.com',
path : '/a/document/path',
secure : false
name : 'name', domain : 'a.domain.com', path : '/a/document/path', secure : false

@@ -62,5 +75,5 @@ }, 'value');

### `void Crumble.remove(Object crumbs)`
#### `void Crumble#remove(Object crumbs)`
Removes a cookie by forcing it to immediately expire.
Removes a cookie from the target document by forcing it to immediately expire.

@@ -70,5 +83,6 @@ The cookie crumbs you can provide are:

* `name` (String, required) - The name of the cookie.
* `path` (String, optional) - The path of which the cookie will be sent. Defaults to `/`.
* `domain` (String, optional) - The (sub)domain of which the cookie will be removed from. The domain can only be a domain that the current document is in, however cookies can cross subdomains. If set to `.` the cookie will be removed from the root domain of the document. Defaults to the domain of the document (i.e. the value of `document.cookie`).
* `path` (String, optional) - The path of which the cookie will be removed from. Defaults to the path of the target document.
* `domain` (String, optional) - The (sub)domain of which the cookie will be removed from. The domain can only be a domain that the target document is in, however cookies can cross subdomains. When set to `.` the cookie will be removed from the root domain of the document. Defaults to the domain of the document (i.e. the value of `document.domain`).
* `secure` (Boolean, optional) - Indicates whether the cookie should only be removed over HTTPS connections. Defaults to `false`.
* `firstPartyOnly` (Boolean, optional) - Indicates whether the cookie should only be sent in a first-party context. This is subject to client support. Defaults to `false`.

@@ -78,3 +92,3 @@ Example usage:

``` js
Crumble.remove(
cookies.remove(
{

@@ -88,6 +102,5 @@ name : 'name'

``` js
Crumble.set(
cookies.set(
{
name : 'name',
value : null
name : 'name', value : undefined
});

@@ -98,16 +111,4 @@ ```

To use Crumble, just use a script tag like so:
It's available through the Node Package Manager (NPM), so you can install it like so:
``` html
<script type="text/javascript" src="path/to/Crumble.js"></script>
```
To remove Crumble from the global namespace, you can use `Crumble.noConflict()`, like so:
``` js
Namespace.Crumble = Crumble.noConflict();
```
Crumble is wrapped using the Universal Module Definition (UMD), so it also works in both CommonJS and AMD environments. It's also available through the Node Package Manage, so you can install Crumble like so:
``` sh

@@ -125,16 +126,12 @@ npm install crumble

which is just an alias for the `default` task:
To only run tests use the `test` task:
``` sh
grunt
grunt test
```
To only check code quality and/or run unit tests use the `test` task:
This also runs code quality checks using JSHint. Please refer to the `.jshintrc` file to familiar yourself with the rules.
``` sh
grunt test
```
## License
Crumble is released under the MIT License.
This project is released under the MIT License.

919

src/Crumble.js

@@ -1,478 +0,587 @@

/* global document : false */
'use strict';
(function (name, factory, context)
// --------------------------------------------------------
/**
* The reserved name of the test cookies created by Crumble.
*
* @private
*
* @static
*
* @final
*
* @type {String}
*
* @memberof Crumble
*/
var TEST_COOKIE_NAME = 'crumble';
/**
* The maximum expiry date a cookie can have.
*
* @private
*
* @static
*
* @final
*
* @type {Date}
*
* @memberof Crumble
*/
var MAXIMUM_EXPIRY_DATE = new Date('Fri, 31 Dec 9999 23:59:59 GMT');
/**
* A shorthand for the root domain.
*
* @private
*
* @static
*
* @final
*
* @type {String}
*
* @memberof Crumble
*/
var ROOT_DOMAIN = '.';
// --------------------------------------------------------
/**
* Determines whether a cookie exists in a given document.
*
* @private
*
* @static
*
* @returns {Boolean} `true` if the cookie exists, otherwise `false`.
*
* @param {HTMLDocument} document The document to search the cookie for.
* @param {String} name The name of the cookie to test the presence of.
*
* @memberof Crumble
*/
function hasCookieInDocument (document, name)
{
if (typeof module !== 'undefined' && module.exports)
return new RegExp('(?:^|.*;)\\s*' + global.encodeURIComponent(name) + '\\s*\\=').test(document.cookie);
}
/**
* Retrieves the value of a cookie in a given document.
*
* @private
*
* @static
*
* @returns {String} The value of the cookie or `null` if the cookie doesn't exist in the document.
*
* @param {HTMLDocument} document The document to search the cookie for.
* @param {String} name The name of the cookie to fetch.
*
* @memberof Crumble
*/
function getCookieInDocument (document, name)
{
var cookie = new RegExp('(?:(?:^|.*;)\\s*' + global.encodeURIComponent(name) + '\\s*\\=\\s*(.*?)(?:;|$))').exec(document.cookie);
if (cookie === null)
{
module.exports = factory.call(context);
return null;
}
else if (typeof define === 'function' && define.amd)
return global.decodeURIComponent( cookie[1] );
}
/**
* Sets a cookie in a given document.
*
* This will set both an `expires` and a `max-age` attribute.
*
* @private
*
* @static
*
* @param {HTMLDocument} document The document to set the cookie for.
* @param {String} name The name of the cookie.
* @param {*} [value] The value of the cookie. When `undefined` or `null` this will be omitted.
* @param {Number} [age] The duration (in milliseconds) of which the cookie can live. When provided any `expires` date is ignored.
* @param {Date} [expires] The expiry date of the cookie, if omitted, the cookie will expire at the end of the session.
* @param {String} [path] The path of which the cookie will be created. Defaults to the path of the document.
* @param {String} [domain] The (sub)domain of which the cookie will be created. It can only be a domain that the target document is in, however cookies can cross subdomains. Defaults to the domain of the document (i.e. the value of `document.domain`).
* @param {Boolean} [secure = false] Indicates whether the cookie should only be passed over HTTPS connections.
* @param {Boolean} [firstPartyOnly = false] Indicates whether the cookie should only be sent in a first-party context. This is subject to client support.
*
* @throws {TypeError} When `name` is `null` or `undefined`.
* @throws {TypeError} When `age` is not a valid number.
* @throws {TypeError} When `expires` does not represent a valid date.
*
* @memberof Crumble
*/
function setCookieInDocument (document, name, value, age, expires, path, domain, secure, firstPartyOnly)
{
if (name === undefined || name === null)
{
define(name, [], factory);
throw new TypeError('The cookie name cannot be `null` or `undefined`.');
}
else
var cookie = global.encodeURIComponent(name) + '=';
// Value.
//
// To keep things tidy, ensure the value is omitted if it
// is `undefined` or `null`.
if (value !== null)
{
context[name] = factory.call(context);
cookie += global.encodeURIComponent(value);
}
}) ('Crumble', function ()
// Path.
if (path)
{
cookie += ';path=' + path;
}
// Domain.
//
// If the provided domain matches the document domain, do
// not bother adding the attribute.
//
// This is to support domains like `localhost`, which when
// explicitly set causes the cookie not to be written.
if (domain && domain !== document.domain)
{
cookie += ';domain=' + domain;
}
// Age.
if (age)
{
if (typeof age !== 'number' || isNaN(age))
{
throw new TypeError('The cookie age must be a valid number.');
}
expires = new Date();
expires.setTime(
expires.getTime() + age
);
// HTTP 1.1.
cookie += ';max-age=' + (age / 1000);
// HTTP 1.0.
cookie += ';expires=' + expires.toUTCString();
}
// Expires.
else if (expires)
{
if (expires instanceof Date && expires.toString() !== 'Invalid Date')
{
age = expires.getTime() - Date.now();
// HTTP 1.1.
cookie += ';max-age=' + (age / 1000);
// HTTP 1.0.
cookie += ';expires=' + expires.toUTCString();
}
else
{
throw new TypeError('The cookie expiry must represent a valid date.');
}
}
// Secure.
if (secure)
{
cookie += ';secure';
}
// First-Party-Only.
if (firstPartyOnly)
{
cookie += ';first-party-only';
}
document.cookie = cookie;
}
/**
* Removes a cookie from a given document by forcing it to immediately expire.
*
* @private
*
* @static
*
* @param {HTMLDocument} document The document to remove the cookie from.
* @param {String} name The name of the cookie to remove.
* @param {String} [path] The path of which the cookie will be removed from.
* @param {String} [domain] The (sub)domain of which the cookie will be removed from. The domain can only be a domain that the target document is in, however cookies can cross subdomains. Defaults to the domain of the document (i.e. the value of `document.domain`).
* @param {Boolean} [secure = false] Indicates whether the cookie should only be removed over HTTPS connections.
* @param {Boolean} [firstPartyOnly = false] Indicates whether the cookie should only be removed in a first-party context. This is subject to client support.
*
* @throws {TypeError} When `name` is `null` or `undefined`.
*
* @memberof Crumble
*/
function removeCookieFromDocument (document, name, path, domain, secure, firstPartyOnly)
{
'use strict';
setCookieInDocument(document, name, undefined, -3600000, undefined, path, domain, secure, firstPartyOnly);
}
// --------------------------------------------------------
/**
* Determines whether cookies are enabled in a given document.
*
* @private
*
* @static
*
* @returns {Boolean} `true` if cookies are enabled, otherwise `false`.
*
* @param {HTMLDocument} document The document to test.
*
* @memberof Crumble
*/
function isCookiesEnabledInDocument (document)
{
setCookieInDocument(
document, TEST_COOKIE_NAME, undefined, undefined, undefined, undefined, undefined, undefined, undefined
);
var isEnabled = hasCookieInDocument(document, TEST_COOKIE_NAME);
removeCookieFromDocument(
document, TEST_COOKIE_NAME, undefined, undefined, undefined
);
return isEnabled;
}
/**
* Retrieves the root domain of a given a document.
*
* For example if the document is on domain `a.b.c.d.co.uk` the root domain will be `d.co.uk`.
*
* @private
*
* @static
*
* @returns {String} The root domain of the given document.
*
* @param {HTMLDocument} document The document to retrieve the root domain from.
*
* @memberof Crumble
*/
function getRootDomainForDocument (document)
{
var domain, domains = document.domain.split('.');
for (var i = 0, l = domains.length; i < l; ++i)
{
domain = domains.slice(-1 - i).join('.');
setCookieInDocument(
document, TEST_COOKIE_NAME, undefined, undefined, undefined, undefined, domain, undefined, undefined
);
if (hasCookieInDocument(document, TEST_COOKIE_NAME))
{
break;
}
}
removeCookieFromDocument(
document, TEST_COOKIE_NAME, undefined, domain, undefined, undefined
);
return domain;
}
// --------------------------------------------------------
/**
* Creates a new Crumble interface to a given document object.
*
* Example usage:
*
* ```
* var cookies = new Crumble(window.document);
*
* if (cookies.isEnabled() === false)
* {
* window.alert('You do not have cookies enabled.');
* }
* ```
*
* @class Crumble
*
* @classdesc A simple wrapper that makes reading the cookies of a given document easy and expressive.
*
* @param {HTMLDocument} document The document that the Crumble will be reading
*
* @throws {TypeError} When `document` does not have both a `cookie` and `domain` property.
*/
function Crumble (document)
{
// Perform some duck type checks to ensure the provided
// document is valid.
if (document === undefined || document.cookie === undefined || document.domain === undefined)
{
throw new TypeError('Crumble expects a document object with at least both a `cookie` and `domain` property.');
}
/**
* The name of any test cookies created by Crumble.
* The document containing the cookie data being read.
*
* @property TEST_COOKIE_NAME
*
* @private
*
* @static
* @instance
*
* @final
* @type {HTMLDocument}
*
* @type {String}
*
* @for Crumble
* @memberof Crumble
*/
var TEST_COOKIE_NAME = 'crumble';
this._document = document;
/**
* The value given to any test cookies created by Crumble.
* The root domain of the document that will be used when setting a cookie with the domain `.`;
*
* @property TEST_COOKIE_VALUE
*
* @private
*
* @static
* @instance
*
* @final
*
* @type {String}
*
* @for Crumble
* @memberof Crumble
*/
var TEST_COOKIE_VALUE = 'nom nom nom';
this._rootDomain = getRootDomainForDocument(document);
}
// --------------------------------------------------------
Crumble.prototype =
{
/**
* The maximum expiry date.
* @ignore
*/
constructor : Crumble,
/**
* Determines whether cookies are enabled in the target document.
*
* @property MAXIMUM_EXPIRY_DATE
* Example usage:
*
* @private
* ```
* if (cookies.isEnabled() === false)
* {
* window.alert('You do not have cookies enabled.');
* }
* ```
*
* @static
* @instance
*
* @final
* @returns {Boolean} `true` if cookies are enabled in this document, otherwise `false`.
*/
isEnabled : function ()
{
return isCookiesEnabledInDocument(this._document);
},
/**
* Retrieves the value of a cookie from the target document.
*
* @type {String}
* Example usage:
*
* @for Crumble
* ```
* var cookie = cookies.get('cookie_name');
* ```
*
* @instance
*
* @returns {String} The value of the cookie. `null` will be returned if the cookie doesn't exist.
*
* @param {String} name The name of the cookie to fetch.
*/
var MAXIMUM_EXPIRY_DATE = new Date('Fri, 31 Dec 9999 23:59:59 GMT');
get : function (name)
{
return getCookieInDocument(this._document, name);
},
// ----------------------------------------------------
/**
* Determines the root domain of the document.
* Determines whether a cookie exists in the target document.
*
* For example if the document is on the `www.test.domain.co.uk` domain, the root domain would be `domain.co.uk`.
* Example usage:
*
* @method getRootDomain
* ```
* var exists = cookies.has('cookie_name');
* ```
*
* @private
* The above is just a more expressive (and faster) way of doing the following:
*
* @static
* ```
* var exists = crumble.get('cookie_name') !== null;
* ```
*
* @for Crumble
* @instance
*
* @return {String} The root domain of the document.
* @returns {Boolean} `true` if the cookie exists in this document, otherwise `false`.
*
* @param {String} name The name of the cookie to test the presence of.
*/
var getRootDomain = (function ()
has : function (name)
{
var _domain, _document;
return hasCookieInDocument(this._document, name);
},
return function ()
{
if (_document !== document)
{
var domains = document.domain.split('.');
for (var i = 0, l = domains.length; i < l; ++i)
{
var domain = domains.slice(-1 - i).join('.');
Crumble.set(
{
name : TEST_COOKIE_NAME, value : TEST_COOKIE_NAME, domain : domain
});
if ( Crumble.has(TEST_COOKIE_NAME) )
{
_domain = domain;
break;
}
}
Crumble.remove(
{
name : TEST_COOKIE_NAME, domain : _domain
});
_document = document;
}
return _domain;
};
}) ();
// ----------------------------------------------------
/**
* A simple utility that abstracts the legacy API that is `document.cookie`.
* Sets a cookie in the target document.
*
* @class Crumble
* Example usage:
*
* @static
* ```
* cookies.set(
* {
* name : 'name', value : 'value', domain : 'a.domain.com', path : '/a/document/path', secure : false
* });
* ```
*
* Alternatively you can separate the value from the cookie crumbs, like so:
*
* ```
* cookies.set(
* {
* name : 'name', domain : 'a.domain.com', path : '/a/document/path', secure : false
*
* }, 'value');
* ```
*
* This is useful as the value is usually the variable when setting a cookie whereas the other cookie crumbs are usually fixed.
*
* @instance
*
* @param {Object} crumbs The crumbs that make the cookie.
* @param {String} crumbs.name The name of the cookie.
* @param {String} [crumbs.value] The value of the cookie. When set to `undefined` the cookie will be removed by forcing it to immediately expire, ignoring any `age` or `expires` crumb that may be provided.
* @param {Number} [crumbs.age] The duration (in milliseconds) of which the cookie can live. When defined, any provided expiry date is ignored. When set to `Infinity` the cookie will be set to expire with date: `31 Dec 9999 23:59:59 GMT`.
* @param {Date|String|Number} [crumbs.expires] The expiry date of the cookie, if omitted, the cookie will expire at the end of the session. You can provide a date object, date string or a timestamp. When provided a timestamp equivalent to `Infinity` the cookie will be set to expire with date: `31 Dec 9999 23:59:59 GMT`.
* @param {String} [crumbs.path] The path of which the cookie will be created. Defaults to the path of the target document.
* @param {String} [crumbs.domain] The (sub)domain of which the cookie will be created. The domain can only be a domain that the target document is in, however cookies can cross subdomains. When set to `.` the domain will be set to the root domain of the target document. Defaults to the domain of the target document (i.e. the value of `document.domain`).
* @param {Boolean} [crumbs.secure = false] Indicates whether the cookie should only be passed over HTTPS connections.
* @param {Boolean} [crumbs.firstPartyOnly = false] Indicates whether the cookie should only be sent in a first-party context. This is subject to client support.
* @param {String} [value] The value of the cookie, see the documentation for `crumbs.value`. When omitted `crumbs.value` will be used.
*
* @throws {TypeError} When `crumbs.name` is `null` or `undefined`.
* @throws {TypeError} When `crumbs.age` is not a valid number.
* @throws {TypeError} When `crumbs.expires` does not represent a valid date.
*/
var Crumble =
set : function (crumbs, value)
{
/**
* Determines whether the client has cookies enabled.
*
* @method isEnabled
*
* @public
*
* @static
*
* @return {Boolean} `true` if cookies are enabled, otherwise `false`.
*
* @todo Should this be cached for the document, as some clients don't require a refresh to
*/
isEnabled : (function ()
{
var _enabled, _document;
var name = crumbs.name,
age = crumbs.age,
expires = crumbs.expires,
path = crumbs.path,
domain = crumbs.domain,
secure = crumbs.secure,
firstPartyOnly = crumbs.firstPartyOnly;
return function ()
{
if (_document !== document)
{
Crumble.set(
{
name : TEST_COOKIE_NAME, value : TEST_COOKIE_VALUE
});
_enabled = Crumble.has(TEST_COOKIE_NAME);
Crumble.remove(
{
name : TEST_COOKIE_NAME
});
_document = document;
}
return _enabled;
};
}) (),
// ------------------------------------------------
/**
* Determines if a cookie exists.
*
* @method has
*
* @public
*
* @static
*
* @return {Boolean} `true` if the cookie exists, otherwise `false`.
*
* @param {String} name The name of the cookie to test the presence of.
*/
has : function (name)
if (value === undefined)
{
return new RegExp('(?:^|.*;)\\s*' + encodeURIComponent(name) + '\\s*\\=').test(document.cookie);
},
value = crumbs.value;
}
/**
* Retrieves the value of a cookie.
*
* @method get
*
* @public
*
* @static
*
* @return {String} The value of the cookie. `null` will be returned if the cookie doesn't exist.
*
* @param {String} name The name of the cookie to fetch.
*/
get : function (name)
// If no cookie value is specified we will remove the
// cookie instead.
if (value === undefined)
{
var cookie = new RegExp('(?:(?:^|.*;)\\s*' + encodeURIComponent(name) + '\\s*\\=\\s*(.*?)(?:;|$))').exec(document.cookie);
removeCookieFromDocument(this._document, name, path, domain, secure, firstPartyOnly);
if (cookie === null)
{
return null;
}
return;
}
return decodeURIComponent( cookie[1] );
},
/**
* Sets a cookie.
*
* Example usage:
*
* ```
* Crumble.set({ name : 'name', value : 'value', domain : 'a.domain.com', path : '/a/document/path', secure : false });
* ```
*
* Alternatively you can separate the value from the cookie crumbs, like so:
*
* ```
* Crumble.set({ name : 'name', domain : 'a.domain.com', path : '/a/document/path', secure : false }, 'value');
* ```
*
* This is useful as the value is usually the variable when setting a cookie whereas the other cookie crumbs are usually fixed.
*
* @method set
*
* @public
*
* @static
*
* @return {void}
*
* @param {Object} crumbs The crumbs that make the cookie.
* @param {String} crumbs.name The name of the cookie.
* @param {String} [crumbs.value] The value of the cookie. If set to `undefined` or `null`; the cookie will be removed by forcing it to immediately expire, ignoring any `age` or `expires` crumb that may be provided.
* @param {Date|String|Number} [crumbs.expires] The expiry date of the cookie, if omitted, the cookie will expire at the end of the session. You can provide a date object, date string or a timestamp. If provided a timestamp equivalent to `Infinity` the cookie will be set to expire with date: `31 Dec 9999 23:59:59 GMT`.
* @param {Number} [crumbs.age] The duration (in minutes) of which the cookie can live. When defined, any provided expiry date is ignored. If set to `Infinity` the cookie will be set to expire with date: `31 Dec 9999 23:59:59 GMT`.
* @param {String} [crumbs.path = '/'] The path of which the cookie will be sent.
* @param {String} [crumbs.domain] The (sub)domain of which the cookie will be sent. The domain can only be a domain that the current document is in, however cookies can cross subdomains. If set to `.` the domain will be set to the root domain of the document. Defaults to the domain of the document (i.e. the value of `document.cookie`).
* @param {Boolean} [crumbs.secure = false] Indicates whether the cookie should only be passed over HTTPS connections.
* @param {String} [value] The value of the cookie, see the documentation for `crumbs.value`. If omitted `crumbs.value` will be used.
*/
set : function (crumbs, value)
if (age)
{
var name = crumbs.name,
expires = crumbs.expires,
age = crumbs.age,
path = crumbs.path,
domain = crumbs.domain,
secure = crumbs.secure;
if (name === undefined || name === null)
if (age === Infinity)
{
throw new Error('[Crumble] Cannot set cookie, a cookie name must be provided');
// Determine the number of seconds between now and the
// maximum allowed expiry date.
age = MAXIMUM_EXPIRY_DATE.getTime() - Date.now();
}
var cookie = encodeURIComponent(name) + '=';
// Ignore.
expires = undefined;
}
if (value === undefined)
{
value = crumbs.value;
}
if (expires)
{
expires = (expires === Infinity) ? MAXIMUM_EXPIRY_DATE : new Date(expires);
// If the value is still `undefined` or is
// `null`, then force the cookie to expire.
//
// Also to keep things tidy, ensure the value
// is also omitted.
if (value === undefined || value === null)
{
age = -1;
}
else
{
cookie += encodeURIComponent(value);
}
// Ignore.
age = undefined;
}
cookie += ';path=' + (path || '/');
if (domain)
{
if (domain === '.')
{
domain = getRootDomain();
}
if (domain !== document.domain)
{
cookie += ';domain=' + domain;
}
}
var now;
if (age !== undefined)
{
now = new Date();
if ( isNaN(age) )
{
throw new Error('[Crumble] Cannot set cookie `' + name + '`, the provided age `' + age + '` is invalid');
}
if (age === Infinity)
{
expires = MAXIMUM_EXPIRY_DATE;
// Determine the number of milliseconds
// between now and the maximum allowed
// expiry date.
age = expires.getTime() - now.getTime();
}
else
{
expires = new Date();
// Convert the age, provided in minutes,
// into milliseconds.
age = age * 60 * 1000;
expires.setTime(
now.getTime() + age
);
}
// HTTP 1.1
cookie += ';max-age=' + age;
// HTTP 1.0
cookie += ';expires=' + expires.toUTCString();
}
else
{
if (expires !== undefined)
{
if (expires.constructor === Number || expires.constructor === String)
{
expires = (expires === Infinity) ? MAXIMUM_EXPIRY_DATE : new Date(expires);
}
// If we don't have a date object at
// this point, we were not provided a
// valid date format in the first place.
if ( !(expires instanceof Date) )
{
throw new Error('[Crumble] Cannot set cookie `' + name + '`, the provided expiry date `' + crumbs.expires + '` is invalid!!!!!');
}
var timestamp = expires.getTime();
// Determine whether the date object is
// valid.
if ( isNaN(timestamp) )
{
throw new Error('[Crumble] Cannot set cookie `' + name + '`, the provided expiry date `' + crumbs.expires + '` is invalid');
}
now = new Date();
// Determine the number of milliseconds
// between now and the expiry date.
age = timestamp - now.getTime();
// HTTP 1.1
cookie += ';max-age=' + age;
// HTTP 1.0
cookie += ';expires=' + expires.toUTCString();
}
}
if (secure)
{
cookie += ';secure';
}
document.cookie = cookie;
},
/**
* Removes a cookie by forcing it to immediately expire.
*
* Example usage:
*
* ```
* Crumble.remove({ name : 'name' });
* ```
*
* The above is just a more expressive way of doing the following:
*
* ```
* Crumble.set({ name : 'name', value : null });
* ```
*
* @method remove
*
* @public
*
* @static
*
* @return {void}
*
* @param {Object} crumbs The crumbs of the cookie to remove.
* @param {String} crumbs.name The name of the cookie.
* @param {String} [crumbs.path = '/'] The path of which the cookie will be removed from.
* @param {String} [crumbs.domain] The (sub)domain of which the cookie will be removed from. The domain can only be a domain that the current document is in, however cookies can cross subdomains. If set to `.` the cookie will be removed from the root domain of the document. Defaults to the domain of the document (i.e. the value of `document.cookie`).
* @param {Boolean} [crumbs.secure = false] Indicates whether the cookie should only be removed over HTTPS connections.
*/
remove : function (crumbs)
if (domain === ROOT_DOMAIN)
{
if (crumbs.name === undefined || crumbs.name === null)
{
throw new Error('[Crumble] Cannot remove cookie, a cookie name must be provided');
}
domain = this._rootDomain;
}
this.set(
{
name : crumbs.name, path : crumbs.path, domain : crumbs.domain, secure : !!crumbs.secure
});
},
setCookieInDocument(this._document, name, value, age, expires, path, domain, secure, firstPartyOnly);
},
// ------------------------------------------------
/**
* Removes a cookie from the target document by forcing it to immediately expire.
*
* Example usage:
*
* ```
* cookies.remove(
* {
* name : 'name'
* });
* ```
*
* The above is just a more expressive way of doing the following:
*
* ```
* cookies.set(
* {
* name : 'name', value : undefined
* });
* ```
*
* @instance
*
* @param {Object} crumbs The crumbs of the cookie to remove.
* @param {String} crumbs.name The name of the cookie.
* @param {String} [crumbs.path] The path of which the cookie will be removed from. Defaults to the path of the target document.
* @param {String} [crumbs.domain] The (sub)domain of which the cookie will be removed from. The domain can only be a domain that the target document is in, however cookies can cross subdomains. When set to `.` the cookie will be removed from the root domain of the target document. Defaults to the domain of the target document (i.e. the value of `document.domain`).
* @param {Boolean} [crumbs.secure = false] Indicates whether the cookie should only be removed over HTTPS connections.
* @param {Boolean} [crumbs.firstPartyOnly = false] Indicates whether the cookie should only be sent in a first-party context. This is subject to client support.
*
* @throws {Error} When `crumbs.name` is `null` or `undefined`.
*/
remove : function (crumbs)
{
var name = crumbs.name,
path = crumbs.path,
domain = crumbs.domain,
secure = crumbs.secure,
firstPartyOnly = crumbs.firstPartyOnly;
/**
* This will remove Crumble from the global namespace, restoring what was there before (if anything). This is for environments that are not using CommonJS or AMD.
*
* Example usage:
*
* ```
* Namespace.Crumble = Crumble.noConflict();
* ```
*
* @method noConflict
*
* @public
*
* @static
*
* @return {Object} The Crumble object to be assigned to any variable you wish.
*/
noConflict : (function (context)
if (domain === ROOT_DOMAIN)
{
var _Crumble = context.Crumble;
domain = this._rootDomain;
}
return function ()
{
context.Crumble = _Crumble;
removeCookieFromDocument(this._document, name, path, domain, secure, firstPartyOnly);
}
};
return this;
};
// --------------------------------------------------------
}) (this)
};
// ----------------------------------------------------
return Crumble;
}, this);
module.exports = Crumble;
.jshintrc
Gruntfile.js
test/Crumble.js
.npmignore

Sorry, the diff of this file is not supported yet