Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jasonkarns/doc-cookies

A little framework: a complete cookies reader/writer with full unicode support
https://github.com/jasonkarns/doc-cookies

Last synced: 5 days ago
JSON representation

A little framework: a complete cookies reader/writer with full unicode support

Awesome Lists containing this project

README 

        
> *This module was taken from a [code snippet](https://developer.mozilla.org/en-US/docs/Web/API/document/cookie#A_little_framework.3A_a_complete_cookies_reader.2Fwriter_with_full_unicode_support) on the MDN docs for `document.cookie`. It has been published as an npm module to facilitate use.*



# doc-cookies

A little framework: a complete cookies reader/writer with full unicode support



Sometimes, cookies being formatted strings, it can be intricate to deal with them in a natural way. The following library aims to abstract the access to document.cookie by defining an object (docCookies) that is partially consistent with a Storage object. It offers also a full unicode support.



> *Note: For never-expire-cookies we used the arbitrarily distant date Fri, 31 Dec 9999 23:59:59 GMT. If for any reason you are afraid of such a date, use the [conventional date of end of the world](http://en.wikipedia.org/wiki/Year_2038_problem) Tue, 19 Jan 2038 03:14:07 GMT – which is the maximum number of seconds elapsed since since 1 January 1970 00:00:00 UTC expressible by a [signed 32-bit integer](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Operators/Bitwise_Operators#Signed_32-bit_integers) (i.e.: 01111111111111111111111111111111, which is `new Date(0x7fffffff * 1e3)`).*



### Writing a cookie



###### Syntax

``` javascript

docCookies.setItem(name, value[, end[, path[, domain[, secure]]]])

```



###### Description

Create/overwrite a cookie.



###### Parameters



name


The name of the cookie to create/overwrite (string).


value


The value of the cookie (string).




end (optional)


The max-age in seconds (e.g. 31536e3 for a year, Infinity for a never-expires cookie), or the expires date in GMTString format or as Date object; if not specified the cookie will expire at the end of session (number – finite or Infinity – string, Date object or null).




path (optional)


The path from where the cookie will be readable. E.g., "/", "/mydir"; if not specified, defaults to the current path of the current document location (string or null). The path must be absolute (see RFC 2965). For more information on how to use relative paths in this argument, see this paragraph.





domain (optional)


The domain from where the cookie will be readable. E.g., "example.com", ".example.com" (includes all subdomains) or "subdomain.example.com"; if not specified, defaults to the host portion of the current document location (string or null).




secure (optional)


The cookie will be transmitted only over secure protocol as https (boolean or null).





### Getting a cookie

###### Syntax

``` javascript

docCookies.getItem(name)

```

###### Description

Read a cookie. If the cookie doesn't exist a [`null`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null) value will be returned.



###### Parameters



name


The name of the cookie to read (string).





### Removing a cookie



###### Syntax

``` javascript

docCookies.removeItem(name[, path[, domain]])

```



###### Description

Delete a cookie.



###### Parameters



name


The name of the cookie to remove (string).




path (optional)


E.g., "/", "/mydir"; if not specified, defaults to the current path of the current document location (string or null). The path must be absolute (see RFC 2965). For more information on how to use relative paths in this argument, see this paragraph.




domain (optional)


E.g., "example.com", ".example.com" (includes all subdomains) or "subdomain.example.com"; if not specified, defaults to the host portion of the current document location (string or null).



Note: To delete cookies that span over subdomains, you need to explicitate the domain attribute in removeItem() as well as setItem().









### Testing a cookie



###### Syntax

``` javascript

docCookies.hasItem(name)

```



###### Description

Check whether a cookie exists in the current position.



###### Parameters



name


The name of the cookie to test (string).





### Getting the list of all cookies

###### Syntax

``` javascript

docCookies.keys()

```



###### Description

Returns an array of all readable cookies from this location.



## Example usage:



``` javascript

docCookies.setItem("test0", "Hello world!");

docCookies.setItem("test1", "Unicode test: \u00E0\u00E8\u00EC\u00F2\u00F9", Infinity);

docCookies.setItem("test2", "Hello world!", new Date(2020, 5, 12));

docCookies.setItem("test3", "Hello world!", new Date(2027, 2, 3), "/blog");

docCookies.setItem("test4", "Hello world!", "Wed, 19 Feb 2127 01:04:55 GMT");

docCookies.setItem("test5", "Hello world!", "Fri, 20 Aug 88354 14:07:15 GMT", "/home");

docCookies.setItem("test6", "Hello world!", 150);

docCookies.setItem("test7", "Hello world!", 245, "/content");

docCookies.setItem("test8", "Hello world!", null, null, "example.com");

docCookies.setItem("test9", "Hello world!", null, null, null, true);

docCookies.setItem("test1;=", "Safe character test;=", Infinity);

 

alert(docCookies.keys().join("\n"));

alert(docCookies.getItem("test1"));

alert(docCookies.getItem("test5"));

docCookies.removeItem("test1");

docCookies.removeItem("test5", "/home");

alert(docCookies.getItem("test1"));

alert(docCookies.getItem("test5"));

alert(docCookies.getItem("unexistingCookie"));

alert(docCookies.getItem());

alert(docCookies.getItem("test1;="));

```