1 | // Type definitions for cookie 0.4
|
---|
2 | // Project: https://github.com/jshttp/cookie
|
---|
3 | // Definitions by: Pine Mizune <https://github.com/pine>
|
---|
4 | // Piotr Błażejewicz <https://github.com/peterblazejewicz>
|
---|
5 | // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
|
---|
6 |
|
---|
7 | /**
|
---|
8 | * Basic HTTP cookie parser and serializer for HTTP servers.
|
---|
9 | */
|
---|
10 |
|
---|
11 | /**
|
---|
12 | * Additional serialization options
|
---|
13 | */
|
---|
14 | export interface CookieSerializeOptions {
|
---|
15 | /**
|
---|
16 | * Specifies the value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.3|Domain Set-Cookie attribute}. By default, no
|
---|
17 | * domain is set, and most clients will consider the cookie to apply to only
|
---|
18 | * the current domain.
|
---|
19 | */
|
---|
20 | domain?: string | undefined;
|
---|
21 |
|
---|
22 | /**
|
---|
23 | * Specifies a function that will be used to encode a cookie's value. Since
|
---|
24 | * value of a cookie has a limited character set (and must be a simple
|
---|
25 | * string), this function can be used to encode a value into a string suited
|
---|
26 | * for a cookie's value.
|
---|
27 | *
|
---|
28 | * The default function is the global `encodeURIComponent`, which will
|
---|
29 | * encode a JavaScript string into UTF-8 byte sequences and then URL-encode
|
---|
30 | * any that fall outside of the cookie range.
|
---|
31 | */
|
---|
32 | encode?(value: string): string;
|
---|
33 |
|
---|
34 | /**
|
---|
35 | * Specifies the `Date` object to be the value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.1|`Expires` `Set-Cookie` attribute}. By default,
|
---|
36 | * no expiration is set, and most clients will consider this a "non-persistent cookie" and will delete
|
---|
37 | * it on a condition like exiting a web browser application.
|
---|
38 | *
|
---|
39 | * *Note* the {@link https://tools.ietf.org/html/rfc6265#section-5.3|cookie storage model specification}
|
---|
40 | * states that if both `expires` and `maxAge` are set, then `maxAge` takes precedence, but it is
|
---|
41 | * possible not all clients by obey this, so if both are set, they should
|
---|
42 | * point to the same date and time.
|
---|
43 | */
|
---|
44 | expires?: Date | undefined;
|
---|
45 | /**
|
---|
46 | * Specifies the boolean value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.6|`HttpOnly` `Set-Cookie` attribute}.
|
---|
47 | * When truthy, the `HttpOnly` attribute is set, otherwise it is not. By
|
---|
48 | * default, the `HttpOnly` attribute is not set.
|
---|
49 | *
|
---|
50 | * *Note* be careful when setting this to true, as compliant clients will
|
---|
51 | * not allow client-side JavaScript to see the cookie in `document.cookie`.
|
---|
52 | */
|
---|
53 | httpOnly?: boolean | undefined;
|
---|
54 | /**
|
---|
55 | * Specifies the number (in seconds) to be the value for the `Max-Age`
|
---|
56 | * `Set-Cookie` attribute. The given number will be converted to an integer
|
---|
57 | * by rounding down. By default, no maximum age is set.
|
---|
58 | *
|
---|
59 | * *Note* the {@link https://tools.ietf.org/html/rfc6265#section-5.3|cookie storage model specification}
|
---|
60 | * states that if both `expires` and `maxAge` are set, then `maxAge` takes precedence, but it is
|
---|
61 | * possible not all clients by obey this, so if both are set, they should
|
---|
62 | * point to the same date and time.
|
---|
63 | */
|
---|
64 | maxAge?: number | undefined;
|
---|
65 | /**
|
---|
66 | * Specifies the value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.4|`Path` `Set-Cookie` attribute}.
|
---|
67 | * By default, the path is considered the "default path".
|
---|
68 | */
|
---|
69 | path?: string | undefined;
|
---|
70 | /**
|
---|
71 | * Specifies the boolean or string to be the value for the {@link https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7|`SameSite` `Set-Cookie` attribute}.
|
---|
72 | *
|
---|
73 | * - `true` will set the `SameSite` attribute to `Strict` for strict same
|
---|
74 | * site enforcement.
|
---|
75 | * - `false` will not set the `SameSite` attribute.
|
---|
76 | * - `'lax'` will set the `SameSite` attribute to Lax for lax same site
|
---|
77 | * enforcement.
|
---|
78 | * - `'strict'` will set the `SameSite` attribute to Strict for strict same
|
---|
79 | * site enforcement.
|
---|
80 | * - `'none'` will set the SameSite attribute to None for an explicit
|
---|
81 | * cross-site cookie.
|
---|
82 | *
|
---|
83 | * More information about the different enforcement levels can be found in {@link https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7|the specification}.
|
---|
84 | *
|
---|
85 | * *note* This is an attribute that has not yet been fully standardized, and may change in the future. This also means many clients may ignore this attribute until they understand it.
|
---|
86 | */
|
---|
87 | sameSite?: true | false | 'lax' | 'strict' | 'none' | undefined;
|
---|
88 | /**
|
---|
89 | * Specifies the boolean value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.5|`Secure` `Set-Cookie` attribute}. When truthy, the
|
---|
90 | * `Secure` attribute is set, otherwise it is not. By default, the `Secure` attribute is not set.
|
---|
91 | *
|
---|
92 | * *Note* be careful when setting this to `true`, as compliant clients will
|
---|
93 | * not send the cookie back to the server in the future if the browser does
|
---|
94 | * not have an HTTPS connection.
|
---|
95 | */
|
---|
96 | secure?: boolean | undefined;
|
---|
97 | }
|
---|
98 |
|
---|
99 | /**
|
---|
100 | * Additional parsing options
|
---|
101 | */
|
---|
102 | export interface CookieParseOptions {
|
---|
103 | /**
|
---|
104 | * Specifies a function that will be used to decode a cookie's value. Since
|
---|
105 | * the value of a cookie has a limited character set (and must be a simple
|
---|
106 | * string), this function can be used to decode a previously-encoded cookie
|
---|
107 | * value into a JavaScript string or other object.
|
---|
108 | *
|
---|
109 | * The default function is the global `decodeURIComponent`, which will decode
|
---|
110 | * any URL-encoded sequences into their byte representations.
|
---|
111 | *
|
---|
112 | * *Note* if an error is thrown from this function, the original, non-decoded
|
---|
113 | * cookie value will be returned as the cookie's value.
|
---|
114 | */
|
---|
115 | decode?(value: string): string;
|
---|
116 | }
|
---|
117 |
|
---|
118 | /**
|
---|
119 | * Parse an HTTP Cookie header string and returning an object of all cookie
|
---|
120 | * name-value pairs.
|
---|
121 | *
|
---|
122 | * @param str the string representing a `Cookie` header value
|
---|
123 | * @param [options] object containing parsing options
|
---|
124 | */
|
---|
125 | export function parse(str: string, options?: CookieParseOptions): { [key: string]: string };
|
---|
126 |
|
---|
127 | /**
|
---|
128 | * Serialize a cookie name-value pair into a `Set-Cookie` header string.
|
---|
129 | *
|
---|
130 | * @param name the name for the cookie
|
---|
131 | * @param value value to set the cookie to
|
---|
132 | * @param [options] object containing serialization options
|
---|
133 | * @throws {TypeError} when `maxAge` options is invalid
|
---|
134 | */
|
---|
135 | export function serialize(name: string, value: string, options?: CookieSerializeOptions): string;
|
---|