| 1 | # cookie
|
|---|
| 2 |
|
|---|
| 3 | [![NPM Version][npm-version-image]][npm-url]
|
|---|
| 4 | [![NPM Downloads][npm-downloads-image]][npm-url]
|
|---|
| 5 | [![Node.js Version][node-image]][node-url]
|
|---|
| 6 | [![Build Status][ci-image]][ci-url]
|
|---|
| 7 | [![Coverage Status][coveralls-image]][coveralls-url]
|
|---|
| 8 |
|
|---|
| 9 | Basic HTTP cookie parser and serializer for HTTP servers.
|
|---|
| 10 |
|
|---|
| 11 | ## Installation
|
|---|
| 12 |
|
|---|
| 13 | This is a [Node.js](https://nodejs.org/en/) module available through the
|
|---|
| 14 | [npm registry](https://www.npmjs.com/). Installation is done using the
|
|---|
| 15 | [`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):
|
|---|
| 16 |
|
|---|
| 17 | ```sh
|
|---|
| 18 | $ npm install cookie
|
|---|
| 19 | ```
|
|---|
| 20 |
|
|---|
| 21 | ## API
|
|---|
| 22 |
|
|---|
| 23 | ```js
|
|---|
| 24 | var cookie = require('cookie');
|
|---|
| 25 | ```
|
|---|
| 26 |
|
|---|
| 27 | ### cookie.parse(str, options)
|
|---|
| 28 |
|
|---|
| 29 | Parse an HTTP `Cookie` header string and returning an object of all cookie name-value pairs.
|
|---|
| 30 | The `str` argument is the string representing a `Cookie` header value and `options` is an
|
|---|
| 31 | optional object containing additional parsing options.
|
|---|
| 32 |
|
|---|
| 33 | ```js
|
|---|
| 34 | var cookies = cookie.parse('foo=bar; equation=E%3Dmc%5E2');
|
|---|
| 35 | // { foo: 'bar', equation: 'E=mc^2' }
|
|---|
| 36 | ```
|
|---|
| 37 |
|
|---|
| 38 | #### Options
|
|---|
| 39 |
|
|---|
| 40 | `cookie.parse` accepts these properties in the options object.
|
|---|
| 41 |
|
|---|
| 42 | ##### decode
|
|---|
| 43 |
|
|---|
| 44 | Specifies a function that will be used to decode a cookie's value. Since the value of a cookie
|
|---|
| 45 | has a limited character set (and must be a simple string), this function can be used to decode
|
|---|
| 46 | a previously-encoded cookie value into a JavaScript string or other object.
|
|---|
| 47 |
|
|---|
| 48 | The default function is the global `decodeURIComponent`, which will decode any URL-encoded
|
|---|
| 49 | sequences into their byte representations.
|
|---|
| 50 |
|
|---|
| 51 | **note** if an error is thrown from this function, the original, non-decoded cookie value will
|
|---|
| 52 | be returned as the cookie's value.
|
|---|
| 53 |
|
|---|
| 54 | ### cookie.serialize(name, value, options)
|
|---|
| 55 |
|
|---|
| 56 | Serialize a cookie name-value pair into a `Set-Cookie` header string. The `name` argument is the
|
|---|
| 57 | name for the cookie, the `value` argument is the value to set the cookie to, and the `options`
|
|---|
| 58 | argument is an optional object containing additional serialization options.
|
|---|
| 59 |
|
|---|
| 60 | ```js
|
|---|
| 61 | var setCookie = cookie.serialize('foo', 'bar');
|
|---|
| 62 | // foo=bar
|
|---|
| 63 | ```
|
|---|
| 64 |
|
|---|
| 65 | #### Options
|
|---|
| 66 |
|
|---|
| 67 | `cookie.serialize` accepts these properties in the options object.
|
|---|
| 68 |
|
|---|
| 69 | ##### domain
|
|---|
| 70 |
|
|---|
| 71 | Specifies the value for the [`Domain` `Set-Cookie` attribute][rfc-6265-5.2.3]. By default, no
|
|---|
| 72 | domain is set, and most clients will consider the cookie to apply to only the current domain.
|
|---|
| 73 |
|
|---|
| 74 | ##### encode
|
|---|
| 75 |
|
|---|
| 76 | Specifies a function that will be used to encode a cookie's value. Since value of a cookie
|
|---|
| 77 | has a limited character set (and must be a simple string), this function can be used to encode
|
|---|
| 78 | a value into a string suited for a cookie's value.
|
|---|
| 79 |
|
|---|
| 80 | The default function is the global `encodeURIComponent`, which will encode a JavaScript string
|
|---|
| 81 | into UTF-8 byte sequences and then URL-encode any that fall outside of the cookie range.
|
|---|
| 82 |
|
|---|
| 83 | ##### expires
|
|---|
| 84 |
|
|---|
| 85 | Specifies the `Date` object to be the value for the [`Expires` `Set-Cookie` attribute][rfc-6265-5.2.1].
|
|---|
| 86 | By default, no expiration is set, and most clients will consider this a "non-persistent cookie" and
|
|---|
| 87 | will delete it on a condition like exiting a web browser application.
|
|---|
| 88 |
|
|---|
| 89 | **note** the [cookie storage model specification][rfc-6265-5.3] states that if both `expires` and
|
|---|
| 90 | `maxAge` are set, then `maxAge` takes precedence, but it is possible not all clients by obey this,
|
|---|
| 91 | so if both are set, they should point to the same date and time.
|
|---|
| 92 |
|
|---|
| 93 | ##### httpOnly
|
|---|
| 94 |
|
|---|
| 95 | Specifies the `boolean` value for the [`HttpOnly` `Set-Cookie` attribute][rfc-6265-5.2.6]. When truthy,
|
|---|
| 96 | the `HttpOnly` attribute is set, otherwise it is not. By default, the `HttpOnly` attribute is not set.
|
|---|
| 97 |
|
|---|
| 98 | **note** be careful when setting this to `true`, as compliant clients will not allow client-side
|
|---|
| 99 | JavaScript to see the cookie in `document.cookie`.
|
|---|
| 100 |
|
|---|
| 101 | ##### maxAge
|
|---|
| 102 |
|
|---|
| 103 | Specifies the `number` (in seconds) to be the value for the [`Max-Age` `Set-Cookie` attribute][rfc-6265-5.2.2].
|
|---|
| 104 | The given number will be converted to an integer by rounding down. By default, no maximum age is set.
|
|---|
| 105 |
|
|---|
| 106 | **note** the [cookie storage model specification][rfc-6265-5.3] states that if both `expires` and
|
|---|
| 107 | `maxAge` are set, then `maxAge` takes precedence, but it is possible not all clients by obey this,
|
|---|
| 108 | so if both are set, they should point to the same date and time.
|
|---|
| 109 |
|
|---|
| 110 | ##### partitioned
|
|---|
| 111 |
|
|---|
| 112 | Specifies the `boolean` value for the [`Partitioned` `Set-Cookie`](rfc-cutler-httpbis-partitioned-cookies)
|
|---|
| 113 | attribute. When truthy, the `Partitioned` attribute is set, otherwise it is not. By default, the
|
|---|
| 114 | `Partitioned` attribute is not set.
|
|---|
| 115 |
|
|---|
| 116 | **note** This is an attribute that has not yet been fully standardized, and may change in the future.
|
|---|
| 117 | This also means many clients may ignore this attribute until they understand it.
|
|---|
| 118 |
|
|---|
| 119 | More information about can be found in [the proposal](https://github.com/privacycg/CHIPS).
|
|---|
| 120 |
|
|---|
| 121 | ##### path
|
|---|
| 122 |
|
|---|
| 123 | Specifies the value for the [`Path` `Set-Cookie` attribute][rfc-6265-5.2.4]. By default, the path
|
|---|
| 124 | is considered the ["default path"][rfc-6265-5.1.4].
|
|---|
| 125 |
|
|---|
| 126 | ##### priority
|
|---|
| 127 |
|
|---|
| 128 | Specifies the `string` to be the value for the [`Priority` `Set-Cookie` attribute][rfc-west-cookie-priority-00-4.1].
|
|---|
| 129 |
|
|---|
| 130 | - `'low'` will set the `Priority` attribute to `Low`.
|
|---|
| 131 | - `'medium'` will set the `Priority` attribute to `Medium`, the default priority when not set.
|
|---|
| 132 | - `'high'` will set the `Priority` attribute to `High`.
|
|---|
| 133 |
|
|---|
| 134 | More information about the different priority levels can be found in
|
|---|
| 135 | [the specification][rfc-west-cookie-priority-00-4.1].
|
|---|
| 136 |
|
|---|
| 137 | **note** This is an attribute that has not yet been fully standardized, and may change in the future.
|
|---|
| 138 | This also means many clients may ignore this attribute until they understand it.
|
|---|
| 139 |
|
|---|
| 140 | ##### sameSite
|
|---|
| 141 |
|
|---|
| 142 | Specifies the `boolean` or `string` to be the value for the [`SameSite` `Set-Cookie` attribute][rfc-6265bis-09-5.4.7].
|
|---|
| 143 |
|
|---|
| 144 | - `true` will set the `SameSite` attribute to `Strict` for strict same site enforcement.
|
|---|
| 145 | - `false` will not set the `SameSite` attribute.
|
|---|
| 146 | - `'lax'` will set the `SameSite` attribute to `Lax` for lax same site enforcement.
|
|---|
| 147 | - `'none'` will set the `SameSite` attribute to `None` for an explicit cross-site cookie.
|
|---|
| 148 | - `'strict'` will set the `SameSite` attribute to `Strict` for strict same site enforcement.
|
|---|
| 149 |
|
|---|
| 150 | More information about the different enforcement levels can be found in
|
|---|
| 151 | [the specification][rfc-6265bis-09-5.4.7].
|
|---|
| 152 |
|
|---|
| 153 | **note** This is an attribute that has not yet been fully standardized, and may change in the future.
|
|---|
| 154 | This also means many clients may ignore this attribute until they understand it.
|
|---|
| 155 |
|
|---|
| 156 | ##### secure
|
|---|
| 157 |
|
|---|
| 158 | Specifies the `boolean` value for the [`Secure` `Set-Cookie` attribute][rfc-6265-5.2.5]. When truthy,
|
|---|
| 159 | the `Secure` attribute is set, otherwise it is not. By default, the `Secure` attribute is not set.
|
|---|
| 160 |
|
|---|
| 161 | **note** be careful when setting this to `true`, as compliant clients will not send the cookie back to
|
|---|
| 162 | the server in the future if the browser does not have an HTTPS connection.
|
|---|
| 163 |
|
|---|
| 164 | ## Example
|
|---|
| 165 |
|
|---|
| 166 | The following example uses this module in conjunction with the Node.js core HTTP server
|
|---|
| 167 | to prompt a user for their name and display it back on future visits.
|
|---|
| 168 |
|
|---|
| 169 | ```js
|
|---|
| 170 | var cookie = require('cookie');
|
|---|
| 171 | var escapeHtml = require('escape-html');
|
|---|
| 172 | var http = require('http');
|
|---|
| 173 | var url = require('url');
|
|---|
| 174 |
|
|---|
| 175 | function onRequest(req, res) {
|
|---|
| 176 | // Parse the query string
|
|---|
| 177 | var query = url.parse(req.url, true, true).query;
|
|---|
| 178 |
|
|---|
| 179 | if (query && query.name) {
|
|---|
| 180 | // Set a new cookie with the name
|
|---|
| 181 | res.setHeader('Set-Cookie', cookie.serialize('name', String(query.name), {
|
|---|
| 182 | httpOnly: true,
|
|---|
| 183 | maxAge: 60 * 60 * 24 * 7 // 1 week
|
|---|
| 184 | }));
|
|---|
| 185 |
|
|---|
| 186 | // Redirect back after setting cookie
|
|---|
| 187 | res.statusCode = 302;
|
|---|
| 188 | res.setHeader('Location', req.headers.referer || '/');
|
|---|
| 189 | res.end();
|
|---|
| 190 | return;
|
|---|
| 191 | }
|
|---|
| 192 |
|
|---|
| 193 | // Parse the cookies on the request
|
|---|
| 194 | var cookies = cookie.parse(req.headers.cookie || '');
|
|---|
| 195 |
|
|---|
| 196 | // Get the visitor name set in the cookie
|
|---|
| 197 | var name = cookies.name;
|
|---|
| 198 |
|
|---|
| 199 | res.setHeader('Content-Type', 'text/html; charset=UTF-8');
|
|---|
| 200 |
|
|---|
| 201 | if (name) {
|
|---|
| 202 | res.write('<p>Welcome back, <b>' + escapeHtml(name) + '</b>!</p>');
|
|---|
| 203 | } else {
|
|---|
| 204 | res.write('<p>Hello, new visitor!</p>');
|
|---|
| 205 | }
|
|---|
| 206 |
|
|---|
| 207 | res.write('<form method="GET">');
|
|---|
| 208 | res.write('<input placeholder="enter your name" name="name"> <input type="submit" value="Set Name">');
|
|---|
| 209 | res.end('</form>');
|
|---|
| 210 | }
|
|---|
| 211 |
|
|---|
| 212 | http.createServer(onRequest).listen(3000);
|
|---|
| 213 | ```
|
|---|
| 214 |
|
|---|
| 215 | ## Testing
|
|---|
| 216 |
|
|---|
| 217 | ```sh
|
|---|
| 218 | $ npm test
|
|---|
| 219 | ```
|
|---|
| 220 |
|
|---|
| 221 | ## Benchmark
|
|---|
| 222 |
|
|---|
| 223 | ```
|
|---|
| 224 | $ npm run bench
|
|---|
| 225 |
|
|---|
| 226 | > cookie@0.5.0 bench
|
|---|
| 227 | > node benchmark/index.js
|
|---|
| 228 |
|
|---|
| 229 | node@18.18.2
|
|---|
| 230 | acorn@8.10.0
|
|---|
| 231 | ada@2.6.0
|
|---|
| 232 | ares@1.19.1
|
|---|
| 233 | brotli@1.0.9
|
|---|
| 234 | cldr@43.1
|
|---|
| 235 | icu@73.2
|
|---|
| 236 | llhttp@6.0.11
|
|---|
| 237 | modules@108
|
|---|
| 238 | napi@9
|
|---|
| 239 | nghttp2@1.57.0
|
|---|
| 240 | nghttp3@0.7.0
|
|---|
| 241 | ngtcp2@0.8.1
|
|---|
| 242 | openssl@3.0.10+quic
|
|---|
| 243 | simdutf@3.2.14
|
|---|
| 244 | tz@2023c
|
|---|
| 245 | undici@5.26.3
|
|---|
| 246 | unicode@15.0
|
|---|
| 247 | uv@1.44.2
|
|---|
| 248 | uvwasi@0.0.18
|
|---|
| 249 | v8@10.2.154.26-node.26
|
|---|
| 250 | zlib@1.2.13.1-motley
|
|---|
| 251 |
|
|---|
| 252 | > node benchmark/parse-top.js
|
|---|
| 253 |
|
|---|
| 254 | cookie.parse - top sites
|
|---|
| 255 |
|
|---|
| 256 | 14 tests completed.
|
|---|
| 257 |
|
|---|
| 258 | parse accounts.google.com x 2,588,913 ops/sec ±0.74% (186 runs sampled)
|
|---|
| 259 | parse apple.com x 2,370,002 ops/sec ±0.69% (186 runs sampled)
|
|---|
| 260 | parse cloudflare.com x 2,213,102 ops/sec ±0.88% (188 runs sampled)
|
|---|
| 261 | parse docs.google.com x 2,194,157 ops/sec ±1.03% (184 runs sampled)
|
|---|
| 262 | parse drive.google.com x 2,265,084 ops/sec ±0.79% (187 runs sampled)
|
|---|
| 263 | parse en.wikipedia.org x 457,099 ops/sec ±0.81% (186 runs sampled)
|
|---|
| 264 | parse linkedin.com x 504,407 ops/sec ±0.89% (186 runs sampled)
|
|---|
| 265 | parse maps.google.com x 1,230,959 ops/sec ±0.98% (186 runs sampled)
|
|---|
| 266 | parse microsoft.com x 926,294 ops/sec ±0.88% (184 runs sampled)
|
|---|
| 267 | parse play.google.com x 2,311,338 ops/sec ±0.83% (185 runs sampled)
|
|---|
| 268 | parse support.google.com x 1,508,850 ops/sec ±0.86% (186 runs sampled)
|
|---|
| 269 | parse www.google.com x 1,022,582 ops/sec ±1.32% (182 runs sampled)
|
|---|
| 270 | parse youtu.be x 332,136 ops/sec ±1.02% (185 runs sampled)
|
|---|
| 271 | parse youtube.com x 323,833 ops/sec ±0.77% (183 runs sampled)
|
|---|
| 272 |
|
|---|
| 273 | > node benchmark/parse.js
|
|---|
| 274 |
|
|---|
| 275 | cookie.parse - generic
|
|---|
| 276 |
|
|---|
| 277 | 6 tests completed.
|
|---|
| 278 |
|
|---|
| 279 | simple x 3,214,032 ops/sec ±1.61% (183 runs sampled)
|
|---|
| 280 | decode x 587,237 ops/sec ±1.16% (187 runs sampled)
|
|---|
| 281 | unquote x 2,954,618 ops/sec ±1.35% (183 runs sampled)
|
|---|
| 282 | duplicates x 857,008 ops/sec ±0.89% (187 runs sampled)
|
|---|
| 283 | 10 cookies x 292,133 ops/sec ±0.89% (187 runs sampled)
|
|---|
| 284 | 100 cookies x 22,610 ops/sec ±0.68% (187 runs sampled)
|
|---|
| 285 | ```
|
|---|
| 286 |
|
|---|
| 287 | ## References
|
|---|
| 288 |
|
|---|
| 289 | - [RFC 6265: HTTP State Management Mechanism][rfc-6265]
|
|---|
| 290 | - [Same-site Cookies][rfc-6265bis-09-5.4.7]
|
|---|
| 291 |
|
|---|
| 292 | [rfc-cutler-httpbis-partitioned-cookies]: https://tools.ietf.org/html/draft-cutler-httpbis-partitioned-cookies/
|
|---|
| 293 | [rfc-west-cookie-priority-00-4.1]: https://tools.ietf.org/html/draft-west-cookie-priority-00#section-4.1
|
|---|
| 294 | [rfc-6265bis-09-5.4.7]: https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-09#section-5.4.7
|
|---|
| 295 | [rfc-6265]: https://tools.ietf.org/html/rfc6265
|
|---|
| 296 | [rfc-6265-5.1.4]: https://tools.ietf.org/html/rfc6265#section-5.1.4
|
|---|
| 297 | [rfc-6265-5.2.1]: https://tools.ietf.org/html/rfc6265#section-5.2.1
|
|---|
| 298 | [rfc-6265-5.2.2]: https://tools.ietf.org/html/rfc6265#section-5.2.2
|
|---|
| 299 | [rfc-6265-5.2.3]: https://tools.ietf.org/html/rfc6265#section-5.2.3
|
|---|
| 300 | [rfc-6265-5.2.4]: https://tools.ietf.org/html/rfc6265#section-5.2.4
|
|---|
| 301 | [rfc-6265-5.2.5]: https://tools.ietf.org/html/rfc6265#section-5.2.5
|
|---|
| 302 | [rfc-6265-5.2.6]: https://tools.ietf.org/html/rfc6265#section-5.2.6
|
|---|
| 303 | [rfc-6265-5.3]: https://tools.ietf.org/html/rfc6265#section-5.3
|
|---|
| 304 |
|
|---|
| 305 | ## License
|
|---|
| 306 |
|
|---|
| 307 | [MIT](LICENSE)
|
|---|
| 308 |
|
|---|
| 309 | [ci-image]: https://badgen.net/github/checks/jshttp/cookie/master?label=ci
|
|---|
| 310 | [ci-url]: https://github.com/jshttp/cookie/actions/workflows/ci.yml
|
|---|
| 311 | [coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/cookie/master
|
|---|
| 312 | [coveralls-url]: https://coveralls.io/r/jshttp/cookie?branch=master
|
|---|
| 313 | [node-image]: https://badgen.net/npm/node/cookie
|
|---|
| 314 | [node-url]: https://nodejs.org/en/download
|
|---|
| 315 | [npm-downloads-image]: https://badgen.net/npm/dm/cookie
|
|---|
| 316 | [npm-url]: https://npmjs.org/package/cookie
|
|---|
| 317 | [npm-version-image]: https://badgen.net/npm/v/cookie
|
|---|
