@tinkoff/browser-cookies
Tiny cookies library for the browser
Fork of browser-cookies
Features
- Clean and easy to use API
- Small footprint
- No dependencies
- RFC6265 compliant
- Cross browser support
Installation
Using npm
npm install @tinkoff/browser-cookies
Using yarn
npm install @tinkoff/browser-cookies
Usage
import { Cookies } from '@tinkoff/browser-cookies';
const cookies = new Cookies({ sameSite: 'lax' });
cookies.set('firstName', 'Lisa');
cookies.set('firstName', 'Lisa', { expires: 365 });
cookies.set('firstName', 'Lisa', { secure: true, domain: 'www.example.org' });
cookies.get('firstName');
cookies.erase('firstName');
API
Cookies
API:
Cookies.set(name
, value
[, options
])
Method to save a cookie.
argument | type | description |
---|
name | string | The name of the cookie to save. |
value | string | The value to save, [percent encoding][ref-percent-encoding] will automatically be applied. Note that only strings are allowed as value, the examples section shows how to save JSON data. |
options | object | May contain any of the properties specified in options below. If an option is not specified, the value configured in Cookies.constructor will be used. |
Cookies.get(name
)
Method that returns a cookie value, or null if the cookie is not found. [Percent encoded][ref-percent-encoding] values will automatically be decoded.
argument | type | description |
---|
name | string | The name of the cookie to retrieve. |
Cookies.erase(name
[, options
])
Method to remove a cookie.
argument | type | description |
---|
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.constructor will be used. |
Cookies.all()
Method to get all cookies.
Returns an object containing all cookie values with the cookie names used as keys. Percent encoded names and values will automatically be decoded.
Cookies.constructor(defaults
)
defaults
argument may be used to change the default value of each option specified in options below.
Options
The options shown in the table below may be set to instance of Cookies.constructor or passed as function argument to Cookies.set() and Cookies.erase(). Also check out the Examples further below.
Name | Type | Default | Description |
---|
expires | Number , Date , String | 0 | Configure when the cookie expires by using one of the following types as value:- A
Number of days until the cookie expires. If set to 0 the cookie will expire at the end of the session. - A
Date object such as new Date(2018, 3, 27) . - A
String in a format recognized by [Date.parse()][ref-date-parse].
|
domain | String | "" | The [domain][ref-cookie-domain] from where the cookie is readable.- If set to
"" 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 all paths. - If set to
"" the cookie will only be readable from the current browser path. - Note that cookies don't support relative paths such as
"../../some/path" so paths must be absolute like "/some/path" .
|
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][ref-httponly], not all browsers support this feature yet.
|
samesite | String | "" | The samesite argument may be used to [prevent cookies from being sent along with cross-site requests][ref-samesite].- If set to
"" the SameSite feature will not be used. - If set to
"Strict" the cookie will only be sent along with "same-site" requests. - If set to
"Lax" the cookie will be sent with "same-site" requests and with "cross-site" top-level navigations. This is an experimental feature as only [a few browsers support SameSite][ref-samesite-caniuse] and [the standard][ref-samesite-spec] has not been finalized yet. Don't use this feature in production environments. |
Examples
Count the number of a visits to a page:
import { Cookies } from '@tinkoff/browser-cookies';
const cookies = new Cookies();
const visits = cookies.get('count') || 0;
console.log("You've been here " + parseInt(visits) + " times before!");
cookies.set('count', parseInt(visits) + 1, {expires: 365});
JSON may be saved by converting the JSON object into a string:
import { Cookies } from '@tinkoff/browser-cookies';
const cookies = new Cookies();
const user = { firstName: 'Sofia', lastName: 'Dueñas' };
cookies.set('user', JSON.stringify(user))
const userString = cookies.get('user');
alert('Hi ' + JSON.parse(userString).firstName);
The default cookie options may be changed:
import { Cookies } from '@tinkoff/browser-cookies';
const cookies = new Cookies({
secure: true,
expires: 7,
});
cookies.set('FirstName', 'John')
cookies.set('LastName', 'Smith', { expires: 30 })
The cookies.all
method can be used for more advanced functionality, for example to erase all cookies except one:
import { Cookies } from '@tinkoff/browser-cookies';
const cookies = new Cookies();
const cookieToKeep = 'FirstName';
const allCookies = cookies.all();
for (let cookieName in allCookies) {
if (allCookies.hasOwnProperty(cookieName) && cookieName != cookieToKeep) {
cookies.erase(cookieName);
}
}