set-cookie-parser

---

ℹ️ Note for current users: I'm considering some changes for the next major version and would appreciate your feedback: https://github.com/nfriedly/set-cookie-parser/discussions/68

---

Parses set-cookie headers into JavaScript objects

Accepts a single set-cookie header value, an array of set-cookie header values, a Node.js response object, or a fetch() Response object that may have 0 or more set-cookie headers.

Also accepts an optional options object. Defaults:

1{
2    decodeValues: true,  // Calls decodeURIComponent on each value - default: true
3    map: false,          // Return an object instead of an array - default: false
4    silent: false,       // Suppress the warning that is logged when called on a request instead of a response - default: false
5}

Returns either an array of cookie objects or a map of name => cookie object with {map: true}. Each cookie object will have, at a minimum name and value properties, and may have additional properties depending on the set-cookie header:

• name - cookie name (string)
• value - cookie value (string)
• path - URL path to limit the scope to (string or undefined)
• domain - domain to expand the scope to (string or undefined, may begin with "." to indicate the named domain or any subdomain of it)
• expires - absolute expiration date for the cookie (Date object or undefined)
• maxAge - relative expiration time of the cookie in seconds from when the client receives it (integer or undefined)
  • Note: when using with express's res.cookie() method, multiply maxAge by 1000 to convert to milliseconds.
• secure - indicates cookie should only be sent over HTTPs (true or undefined)
• httpOnly - indicates cookie should not be accessible to client-side JavaScript (true or undefined)
• sameSite - indicates if cookie should be included in cross-site requests (more info) (string or undefined)
  • Note: valid values are "Strict", "Lax", and "None", but set-cookie-parser coppies the value verbatim and does not perform any validation.
• partitioned - indicates cookie should be scoped to the combination of 3rd party domain + top page domain (more info) (true or undefined)

(The output format is loosely based on the input format of https://www.npmjs.com/package/cookie)

Install

1$ npm install --save set-cookie-parser

Usage

Get array of cookie objects

1var http = require('http');
2var setCookie = require('set-cookie-parser');
3
4http.get('http://example.com', function(res) {
5  var cookies = setCookie.parse(res, {
6    decodeValues: true  // default: true
7  });
8
9  cookies.forEach(console.log);
10}

Example output:

1[
2    {
3        name: 'bam',
4        value: 'baz'
5    },
6    {
7        name: 'foo',
8        value: 'bar',
9        path: '/',
10        expires: new Date('Tue Jul 01 2025 06:01:11 GMT-0400 (EDT)'),
11        maxAge: 1000,
12        domain: '.example.com',
13        secure: true,
14        httpOnly: true,
15        sameSite: 'lax'
16    }
17]

Get map of cookie objects

1var http = require('http');
2var setCookie = require('set-cookie-parser');
3
4http.get('http://example.com', function(res) {
5  var cookies = setCookie.parse(res, {
6    decodeValues: true,  // default: true
7    map: true            // default: false
8  });
9
10  var desiredCookie = cookies['session'];
11  console.log(desiredCookie);
12});

Example output:

1{
2    bam: {
3        name: 'bam',
4        value: 'baz'
5    },
6    foo: {
7        name: 'foo',
8        value: 'bar',
9        path: '/',
10        expires: new Date('Tue Jul 01 2025 06:01:11 GMT-0400 (EDT)'),
11        maxAge: 1000,
12        domain: '.example.com',
13        secure: true,
14        httpOnly: true,
15        sameSite: 'lax'
16    }
17}

Creating a new, modified set-cookie header

This library can be used in conjunction with the cookie library to modify and replace set-cookie headers:

1const libCookie = require('cookie');
2const setCookie = require('set-cookie-parser');
3
4function modifySetCookie(res){
5  // parse the set-cookie headers with this library
6  let cookies = setCookie.parse(res);
7  
8  // modify the cookies here
9  // ...
10  
11  // create new set-cookie headers using the cookie library
12  res.headers['set-cookie'] = cookies.map(function(cookie) {
13      return libCookie.serialize(cookie.name, cookie.value, cookie);
14  });
15}

See a real-world example of this in unblocker

Usage in React Native (and with some other fetch implementations)

React Native follows the Fetch spec more closely and combines all of the Set-Cookie header values into a single string. The splitCookiesString method reverses this.

1var setCookie = require('set-cookie-parser');
2
3var response = fetch(/*...*/);
4
5// This is mainly for React Native; Node.js does not combine set-cookie headers.
6var combinedCookieHeader = response.headers.get('Set-Cookie');
7var splitCookieHeaders = setCookie.splitCookiesString(combinedCookieHeader)
8var cookies = setCookie.parse(splitCookieHeaders);
9
10console.log(cookies); // should be an array of cookies

This behavior may become a default part of parse in the next major release, but requires the extra step for now.

Note that the fetch() spec now includes a getSetCookie() method that provides un-combined Set-Cookie headers. This library will automatically use that method if it is present.

API

parse(input, [options])

Parses cookies from a string, array of strings, or a http response object. Always returns an array, regardless of input format. (Unless the map option is set, in which case it always returns an object.)

parseString(individualSetCookieHeader, [options])

Parses a single set-cookie header value string. Options default is {decodeValues: true}. Used under-the-hood by parse(). Returns an object.

splitCookiesString(combinedSetCookieHeader)

It's uncommon, but the HTTP spec does allow for multiple of the same header to have their values combined (comma-separated) into a single header. This method splits apart a combined header without choking on commas that appear within a cookie's value (or expiration date). Returns an array of strings that may be passed to parse().

References

• RFC 6265: HTTP State Management Mechanism
• draft-ietf-httpbis-rfc6265bis-10

License

MIT © Nathan Friedly