Isomorphic Cookies

Isomorphic bulletproof cookie functions for Client and Server.

• 100% Tests coverage
• Works on both Server and Client
• Support for unicode
• Support for String, Boolean, Object and Array as a values
• IE support, thanks to @derwok
• Looking for Client's (Browser) persistent storage? Try ClientStorage package

Install:

meteor add ostrio:cookies

ES6 Import:

1import { Cookies } from 'meteor/ostrio:cookies';

API:

Note: On a server, cookies will be set only after headers are sent (on next route or page reload). To send cookies from Client to Server without a page reload use send() method.

Server Usage Note: On a server Cookies implemented as a middleware. To get access to current user's cookies use req.Cookies instance. For more - see examples section below.

Fetch cookies new Cookies(opts) [Isomorphic]

Create new instance of Cookies

• opts.auto {Boolean} - [Server] Auto-bind in middleware as req.Cookies, by default true
• opts.handler {Function} - [Server] Middleware function with one argument cookies as Cookies instance. See "Alternate Usage" section
• opts.TTL {Number} - Default cookies expiration time (max-age) in milliseconds, by default - session (no TTL)
• opts.runOnServer {Boolean} - Set to false to avoid server usage (by default - true)

1import { Cookies } from 'meteor/ostrio:cookies';
2const cookies = new Cookies();

cookies.get(key) [Isomorphic]

Read a cookie. If the cookie doesn't exist a null will be returned.

• key {String} - The name of the cookie to read

cookies.set(key, value, [opts]) [Isomorphic]

Create/overwrite a cookie.

• key {String} - The name of the cookie to create/overwrite
• value {String|Number|Boolean|Object|Array} - The value of the cookie
• opts {Object} - [Optional]
• opts.expires {Number|Date|Infinity} - [Optional] Date, Number as milliseconds or Infinity for a never-expires cookie. If not specified the cookie will expire at the end of session (number as milliseconds or Date object)
• opts.maxAge {Number} - [Optional] The max-age in seconds (e.g. 31536e3 for a year)
• opts.path {String} - [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: docs
• opts.domain {String} - [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)
• opts.secure {Boolean} - [Optional] The cookie will be transmitted only over secure protocol as https
• opts.httpOnly {Boolean} - [Optional] An HttpOnly cookie cannot be accessed by client-side APIs, such as JavaScript. This restriction eliminates the threat of cookie theft via cross-site scripting (XSS)
• opts.sameSite {Boolean} - [Optional] Cookie which can only be sent in requests originating from the same origin as the target domain. Read more on wikipedia and ietf
• opts.firstPartyOnly {Boolean} - [Optional] Deprecated use sameSite instead

cookies.remove([key], [path], [domain]) [Isomorphic]

• remove() - Remove all cookies on current domain
• remove(key) - Remove a cookie on current domain
• remove(key, path, domain):
  • key {String} - The name of the cookie to create/overwrite
  • path {String} - [Optional] The path from where the cookie was 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: https://developer.mozilla.org/en-US/docs/Web/API/document.cookie#Using_relative_URLs_in_the_path_parameter
  • domain {String} - [Optional] The domain from where the cookie was 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)

cookies.has(key) [Isomorphic]

Check whether a cookie exists in the current position, returns boolean value

• key {String} - The name of the cookie to check

cookies.keys() [Isomorphic]

Returns an array of all readable cookies from this location

cookies.send([callback]) [Client]

Send all current cookies to server

Examples:

1/* Both Client & Server */
2import { Cookies } from 'meteor/ostrio:cookies';
3const cookies = new Cookies();
4
5/* Client */
6if (Meteor.isClient) {
7  cookies.set('locale', 'en'); //true
8  cookies.set('country', 'usa'); //true
9  cookies.set('gender', 'male'); //true
10
11  cookies.get('gender'); //male
12
13  cookies.has('locale'); //true
14  cookies.has('city'); //false
15
16  cookies.keys(); //['locale', 'country', 'gender']
17
18  cookies.remove('locale'); //true
19  cookies.get('locale'); //undefined
20
21  cookies.keys(); //['country', 'gender']
22
23  cookies.remove(); //true
24  cookies.keys(); //[""]
25
26  cookies.remove(); //false
27}
28
29/* Server */
30if (Meteor.isServer) {
31  WebApp.connectHandlers.use((req, res, next) => {
32    cookies = req.Cookies;
33
34    cookies.set('locale', 'en'); //true
35    cookies.set('country', 'usa'); //true
36    cookies.set('gender', 'male'); //true
37
38    cookies.get('gender'); //male
39
40    cookies.has('locale'); //true
41    cookies.has('city'); //false
42
43    cookies.keys(); //['locale', 'country', 'gender']
44
45    cookies.remove('locale'); //true
46    cookies.get('locale'); //undefined
47
48    cookies.keys(); //['country', 'gender']
49
50    cookies.remove(); //true
51    cookies.keys(); //[""]
52
53    cookies.remove(); //false
54  });
55}

Alternate Usage

1/* Both Client & Server */
2import { Cookies } from 'meteor/ostrio:cookies';
3
4/* Client */
5if (Meteor.isClient) {
6  const cookies = new Cookies();
7  cookies.set('gender', 'male'); //true
8  cookies.get('gender'); //male
9  cookies.has('city'); //false
10  cookies.keys(); //['gender']
11}
12
13/* Server */
14if (Meteor.isServer) {
15  const cookie = new Cookies({
16    auto: false, // Do not bind as a middleware by default
17    handler(cookies) {
18      cookies.set('gender', 'male'); //true
19      cookies.get('gender'); //male
20      cookies.has('city'); //false
21      cookies.keys(); //['gender']
22    }
23  });
24
25  WebApp.connectHandlers.use(cookie.middleware());
26}

Support this project:

This project wouldn't be possible without ostr.io.

Using ostr.io you are not only protecting domain names, monitoring websites and servers, using Prerendering for better SEO of your JavaScript website, but support our Open Source activity, and great packages like this one could be available for free.