README.md (8208B)
1 # cookie 2 3 [![NPM Version][npm-image]][npm-url] 4 [![NPM Downloads][downloads-image]][downloads-url] 5 [![Node.js Version][node-version-image]][node-version-url] 6 [![Build Status][travis-image]][travis-url] 7 [![Test Coverage][coveralls-image]][coveralls-url] 8 9 Basic HTTP cookie parser and serializer for HTTP servers. 10 11 ## Installation 12 13 ```sh 14 $ npm install cookie 15 ``` 16 17 ## API 18 19 ```js 20 var cookie = require('cookie'); 21 ``` 22 23 ### cookie.parse(str, options) 24 25 Parse an HTTP `Cookie` header string and returning an object of all cookie name-value pairs. 26 The `str` argument is the string representing a `Cookie` header value and `options` is an 27 optional object containing additional parsing options. 28 29 ```js 30 var cookies = cookie.parse('foo=bar; equation=E%3Dmc%5E2'); 31 // { foo: 'bar', equation: 'E=mc^2' } 32 ``` 33 34 #### Options 35 36 `cookie.parse` accepts these properties in the options object. 37 38 ##### decode 39 40 Specifies a function that will be used to decode a cookie's value. Since the value of a cookie 41 has a limited character set (and must be a simple string), this function can be used to decode 42 a previously-encoded cookie value into a JavaScript string or other object. 43 44 The default function is the global `decodeURIComponent`, which will decode any URL-encoded 45 sequences into their byte representations. 46 47 **note** if an error is thrown from this function, the original, non-decoded cookie value will 48 be returned as the cookie's value. 49 50 ### cookie.serialize(name, value, options) 51 52 Serialize a cookie name-value pair into a `Set-Cookie` header string. The `name` argument is the 53 name for the cookie, the `value` argument is the value to set the cookie to, and the `options` 54 argument is an optional object containing additional serialization options. 55 56 ```js 57 var setCookie = cookie.serialize('foo', 'bar'); 58 // foo=bar 59 ``` 60 61 #### Options 62 63 `cookie.serialize` accepts these properties in the options object. 64 65 ##### domain 66 67 Specifies the value for the [`Domain` `Set-Cookie` attribute][rfc-6266-5.2.3]. By default, no 68 domain is set, and most clients will consider the cookie to apply to only the current domain. 69 70 ##### encode 71 72 Specifies a function that will be used to encode a cookie's value. Since value of a cookie 73 has a limited character set (and must be a simple string), this function can be used to encode 74 a value into a string suited for a cookie's value. 75 76 The default function is the global `ecodeURIComponent`, which will encode a JavaScript string 77 into UTF-8 byte sequences and then URL-encode any that fall outside of the cookie range. 78 79 ##### expires 80 81 Specifies the `Date` object to be the value for the [`Expires` `Set-Cookie` attribute][rfc-6266-5.2.1]. 82 By default, no expiration is set, and most clients will consider this a "non-persistent cookie" and 83 will delete it on a condition like exiting a web browser application. 84 85 **note** the [cookie storage model specification][rfc-6266-5.3] states that if both `expires` and 86 `magAge` are set, then `maxAge` takes precedence, but it is possiblke not all clients by obey this, 87 so if both are set, they should point to the same date and time. 88 89 ##### httpOnly 90 91 Specifies the `boolean` value for the [`HttpOnly` `Set-Cookie` attribute][rfc-6266-5.2.6]. When truthy, 92 the `HttpOnly` attribute is set, otherwise it is not. By default, the `HttpOnly` attribute is not set. 93 94 **note** be careful when setting this to `true`, as compliant clients will not allow client-side 95 JavaScript to see the cookie in `document.cookie`. 96 97 ##### maxAge 98 99 Specifies the `number` (in seconds) to be the value for the [`Max-Age` `Set-Cookie` attribute][rfc-6266-5.2.2]. 100 The given number will be converted to an integer by rounding down. By default, no maximum age is set. 101 102 **note** the [cookie storage model specification][rfc-6266-5.3] states that if both `expires` and 103 `magAge` are set, then `maxAge` takes precedence, but it is possiblke not all clients by obey this, 104 so if both are set, they should point to the same date and time. 105 106 ##### path 107 108 Specifies the value for the [`Path` `Set-Cookie` attribute][rfc-6266-5.2.4]. By default, the path 109 is considered the ["default path"][rfc-6266-5.1.4]. By default, no maximum age is set, and most 110 clients will consider this a "non-persistent cookie" and will delete it on a condition like exiting 111 a web browser application. 112 113 ##### sameSite 114 115 Specifies the `boolean` or `string` to be the value for the [`SameSite` `Set-Cookie` attribute][draft-west-first-party-cookies-07]. 116 117 - `true` will set the `SameSite` attribute to `Strict` for strict same site enforcement. 118 - `false` will not set the `SameSite` attribute. 119 - `'lax'` will set the `SameSite` attribute to `Lax` for lax same site enforcement. 120 - `'strict'` will set the `SameSite` attribute to `Strict` for strict same site enforcement. 121 122 More information about the different enforcement levels can be found in the specification 123 https://tools.ietf.org/html/draft-west-first-party-cookies-07#section-4.1.1 124 125 **note** This is an attribute that has not yet been fully standardized, and may change in the future. 126 This also means many clients may ignore this attribute until they understand it. 127 128 ##### secure 129 130 Specifies the `boolean` value for the [`Secure` `Set-Cookie` attribute][rfc-6266-5.2.5]. When truthy, 131 the `Secure` attribute is set, otherwise it is not. By default, the `Secure` attribute is not set. 132 133 **note** be careful when setting this to `true`, as compliant clients will not send the cookie back to 134 the server in the future if the browser does not have an HTTPS connection. 135 136 ## Example 137 138 The following example uses this module in conjunction with the Node.js core HTTP server 139 to prompt a user for their name and display it back on future visits. 140 141 ```js 142 var cookie = require('cookie'); 143 var escapeHtml = require('escape-html'); 144 var http = require('http'); 145 var url = require('url'); 146 147 function onRequest(req, res) { 148 // Parse the query string 149 var query = url.parse(req.url, true, true).query; 150 151 if (query && query.name) { 152 // Set a new cookie with the name 153 res.setHeader('Set-Cookie', cookie.serialize('name', String(query.name), { 154 httpOnly: true, 155 maxAge: 60 * 60 * 24 * 7 // 1 week 156 })); 157 158 // Redirect back after setting cookie 159 res.statusCode = 302; 160 res.setHeader('Location', req.headers.referer || '/'); 161 res.end(); 162 return; 163 } 164 165 // Parse the cookies on the request 166 var cookies = cookie.parse(req.headers.cookie || ''); 167 168 // Get the visitor name set in the cookie 169 var name = cookies.name; 170 171 res.setHeader('Content-Type', 'text/html; charset=UTF-8'); 172 173 if (name) { 174 res.write('<p>Welcome back, <b>' + escapeHtml(name) + '</b>!</p>'); 175 } else { 176 res.write('<p>Hello, new visitor!</p>'); 177 } 178 179 res.write('<form method="GET">'); 180 res.write('<input placeholder="enter your name" name="name"> <input type="submit" value="Set Name">'); 181 res.end('</form'); 182 } 183 184 http.createServer(onRequest).listen(3000); 185 ``` 186 187 ## Testing 188 189 ```sh 190 $ npm test 191 ``` 192 193 ## References 194 195 - [RFC 6266: HTTP State Management Mechanism][rfc-6266] 196 - [Same-site Cookies][draft-west-first-party-cookies-07] 197 198 [draft-west-first-party-cookies-07]: https://tools.ietf.org/html/draft-west-first-party-cookies-07 199 [rfc-6266]: https://tools.ietf.org/html/rfc6266 200 [rfc-6266-5.1.4]: https://tools.ietf.org/html/rfc6266#section-5.1.4 201 [rfc-6266-5.2.1]: https://tools.ietf.org/html/rfc6266#section-5.2.1 202 [rfc-6266-5.2.2]: https://tools.ietf.org/html/rfc6266#section-5.2.2 203 [rfc-6266-5.2.3]: https://tools.ietf.org/html/rfc6266#section-5.2.3 204 [rfc-6266-5.2.4]: https://tools.ietf.org/html/rfc6266#section-5.2.4 205 [rfc-6266-5.3]: https://tools.ietf.org/html/rfc6266#section-5.3 206 207 ## License 208 209 [MIT](LICENSE) 210 211 [npm-image]: https://img.shields.io/npm/v/cookie.svg 212 [npm-url]: https://npmjs.org/package/cookie 213 [node-version-image]: https://img.shields.io/node/v/cookie.svg 214 [node-version-url]: https://nodejs.org/en/download 215 [travis-image]: https://img.shields.io/travis/jshttp/cookie/master.svg 216 [travis-url]: https://travis-ci.org/jshttp/cookie 217 [coveralls-image]: https://img.shields.io/coveralls/jshttp/cookie/master.svg 218 [coveralls-url]: https://coveralls.io/r/jshttp/cookie?branch=master 219 [downloads-image]: https://img.shields.io/npm/dm/cookie.svg 220 [downloads-url]: https://npmjs.org/package/cookie