source: trip-planner-front/node_modules/cookie/README.md@ fa375fe

Last change on this file since fa375fe was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 8.8 KB
Line 
1# cookie
2
3[![NPM Version][npm-version-image]][npm-url]
4[![NPM Downloads][npm-downloads-image]][npm-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
9Basic HTTP cookie parser and serializer for HTTP servers.
10
11## Installation
12
13This 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
24var cookie = require('cookie');
25```
26
27### cookie.parse(str, options)
28
29Parse an HTTP `Cookie` header string and returning an object of all cookie name-value pairs.
30The `str` argument is the string representing a `Cookie` header value and `options` is an
31optional object containing additional parsing options.
32
33```js
34var 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
44Specifies a function that will be used to decode a cookie's value. Since the value of a cookie
45has a limited character set (and must be a simple string), this function can be used to decode
46a previously-encoded cookie value into a JavaScript string or other object.
47
48The default function is the global `decodeURIComponent`, which will decode any URL-encoded
49sequences into their byte representations.
50
51**note** if an error is thrown from this function, the original, non-decoded cookie value will
52be returned as the cookie's value.
53
54### cookie.serialize(name, value, options)
55
56Serialize a cookie name-value pair into a `Set-Cookie` header string. The `name` argument is the
57name for the cookie, the `value` argument is the value to set the cookie to, and the `options`
58argument is an optional object containing additional serialization options.
59
60```js
61var 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
71Specifies the value for the [`Domain` `Set-Cookie` attribute][rfc-6265-5.2.3]. By default, no
72domain is set, and most clients will consider the cookie to apply to only the current domain.
73
74##### encode
75
76Specifies a function that will be used to encode a cookie's value. Since value of a cookie
77has a limited character set (and must be a simple string), this function can be used to encode
78a value into a string suited for a cookie's value.
79
80The default function is the global `encodeURIComponent`, which will encode a JavaScript string
81into UTF-8 byte sequences and then URL-encode any that fall outside of the cookie range.
82
83##### expires
84
85Specifies the `Date` object to be the value for the [`Expires` `Set-Cookie` attribute][rfc-6265-5.2.1].
86By default, no expiration is set, and most clients will consider this a "non-persistent cookie" and
87will 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,
91so if both are set, they should point to the same date and time.
92
93##### httpOnly
94
95Specifies the `boolean` value for the [`HttpOnly` `Set-Cookie` attribute][rfc-6265-5.2.6]. When truthy,
96the `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
99JavaScript to see the cookie in `document.cookie`.
100
101##### maxAge
102
103Specifies the `number` (in seconds) to be the value for the [`Max-Age` `Set-Cookie` attribute][rfc-6265-5.2.2].
104The 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,
108so if both are set, they should point to the same date and time.
109
110##### path
111
112Specifies the value for the [`Path` `Set-Cookie` attribute][rfc-6265-5.2.4]. By default, the path
113is considered the ["default path"][rfc-6265-5.1.4].
114
115##### sameSite
116
117Specifies the `boolean` or `string` to be the value for the [`SameSite` `Set-Cookie` attribute][rfc-6265bis-03-4.1.2.7].
118
119 - `true` will set the `SameSite` attribute to `Strict` for strict same site enforcement.
120 - `false` will not set the `SameSite` attribute.
121 - `'lax'` will set the `SameSite` attribute to `Lax` for lax same site enforcement.
122 - `'none'` will set the `SameSite` attribute to `None` for an explicit cross-site cookie.
123 - `'strict'` will set the `SameSite` attribute to `Strict` for strict same site enforcement.
124
125More information about the different enforcement levels can be found in
126[the specification][rfc-6265bis-03-4.1.2.7].
127
128**note** This is an attribute that has not yet been fully standardized, and may change in the future.
129This also means many clients may ignore this attribute until they understand it.
130
131##### secure
132
133Specifies the `boolean` value for the [`Secure` `Set-Cookie` attribute][rfc-6265-5.2.5]. When truthy,
134the `Secure` attribute is set, otherwise it is not. By default, the `Secure` attribute is not set.
135
136**note** be careful when setting this to `true`, as compliant clients will not send the cookie back to
137the server in the future if the browser does not have an HTTPS connection.
138
139## Example
140
141The following example uses this module in conjunction with the Node.js core HTTP server
142to prompt a user for their name and display it back on future visits.
143
144```js
145var cookie = require('cookie');
146var escapeHtml = require('escape-html');
147var http = require('http');
148var url = require('url');
149
150function onRequest(req, res) {
151 // Parse the query string
152 var query = url.parse(req.url, true, true).query;
153
154 if (query && query.name) {
155 // Set a new cookie with the name
156 res.setHeader('Set-Cookie', cookie.serialize('name', String(query.name), {
157 httpOnly: true,
158 maxAge: 60 * 60 * 24 * 7 // 1 week
159 }));
160
161 // Redirect back after setting cookie
162 res.statusCode = 302;
163 res.setHeader('Location', req.headers.referer || '/');
164 res.end();
165 return;
166 }
167
168 // Parse the cookies on the request
169 var cookies = cookie.parse(req.headers.cookie || '');
170
171 // Get the visitor name set in the cookie
172 var name = cookies.name;
173
174 res.setHeader('Content-Type', 'text/html; charset=UTF-8');
175
176 if (name) {
177 res.write('<p>Welcome back, <b>' + escapeHtml(name) + '</b>!</p>');
178 } else {
179 res.write('<p>Hello, new visitor!</p>');
180 }
181
182 res.write('<form method="GET">');
183 res.write('<input placeholder="enter your name" name="name"> <input type="submit" value="Set Name">');
184 res.end('</form>');
185}
186
187http.createServer(onRequest).listen(3000);
188```
189
190## Testing
191
192```sh
193$ npm test
194```
195
196## Benchmark
197
198```
199$ npm run bench
200
201> cookie@0.3.1 bench cookie
202> node benchmark/index.js
203
204 http_parser@2.8.0
205 node@6.14.2
206 v8@5.1.281.111
207 uv@1.16.1
208 zlib@1.2.11
209 ares@1.10.1-DEV
210 icu@58.2
211 modules@48
212 napi@3
213 openssl@1.0.2o
214
215> node benchmark/parse.js
216
217 cookie.parse
218
219 6 tests completed.
220
221 simple x 1,200,691 ops/sec ±1.12% (189 runs sampled)
222 decode x 1,012,994 ops/sec ±0.97% (186 runs sampled)
223 unquote x 1,074,174 ops/sec ±2.43% (186 runs sampled)
224 duplicates x 438,424 ops/sec ±2.17% (184 runs sampled)
225 10 cookies x 147,154 ops/sec ±1.01% (186 runs sampled)
226 100 cookies x 14,274 ops/sec ±1.07% (187 runs sampled)
227```
228
229## References
230
231- [RFC 6265: HTTP State Management Mechanism][rfc-6265]
232- [Same-site Cookies][rfc-6265bis-03-4.1.2.7]
233
234[rfc-6265bis-03-4.1.2.7]: https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7
235[rfc-6265]: https://tools.ietf.org/html/rfc6265
236[rfc-6265-5.1.4]: https://tools.ietf.org/html/rfc6265#section-5.1.4
237[rfc-6265-5.2.1]: https://tools.ietf.org/html/rfc6265#section-5.2.1
238[rfc-6265-5.2.2]: https://tools.ietf.org/html/rfc6265#section-5.2.2
239[rfc-6265-5.2.3]: https://tools.ietf.org/html/rfc6265#section-5.2.3
240[rfc-6265-5.2.4]: https://tools.ietf.org/html/rfc6265#section-5.2.4
241[rfc-6265-5.2.5]: https://tools.ietf.org/html/rfc6265#section-5.2.5
242[rfc-6265-5.2.6]: https://tools.ietf.org/html/rfc6265#section-5.2.6
243[rfc-6265-5.3]: https://tools.ietf.org/html/rfc6265#section-5.3
244
245## License
246
247[MIT](LICENSE)
248
249[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/cookie/master
250[coveralls-url]: https://coveralls.io/r/jshttp/cookie?branch=master
251[node-version-image]: https://badgen.net/npm/node/cookie
252[node-version-url]: https://nodejs.org/en/download
253[npm-downloads-image]: https://badgen.net/npm/dm/cookie
254[npm-url]: https://npmjs.org/package/cookie
255[npm-version-image]: https://badgen.net/npm/v/cookie
256[travis-image]: https://badgen.net/travis/jshttp/cookie/master
257[travis-url]: https://travis-ci.org/jshttp/cookie
Note: See TracBrowser for help on using the repository browser.