From e711a9f357687f3ac0609a27636bd01967372954 Mon Sep 17 00:00:00 2001 From: Blake Embrey Date: Fri, 4 Oct 2024 17:30:13 -0700 Subject: [PATCH] Match docs between code/README --- README.md | 101 ++++++++++++++++++++------------------------------- src/index.ts | 89 ++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 128 insertions(+), 62 deletions(-) diff --git a/README.md b/README.md index fb0c3c6..40fbc76 100644 --- a/README.md +++ b/README.md @@ -39,12 +39,12 @@ const cookies = cookie.parse("foo=bar; equation=E%3Dmc%5E2"); Specifies a function that will be used to decode a cookie's value. Since the value of a cookie has a limited character set (and must be a simple string), this function can be used to decode -a previously-encoded cookie value into a JavaScript string or other object. +a previously-encoded cookie value into a JavaScript string. The default function is the global `decodeURIComponent`, which will decode any URL-encoded sequences into their byte representations. -**note** if an error is thrown from this function, the original, non-decoded cookie value will +If an error is thrown from this function, the original, non-decoded cookie value will be returned as the cookie's value. ### cookie.serialize(name, value, options) @@ -62,11 +62,6 @@ const setCookie = cookie.serialize("foo", "bar"); `cookie.serialize` accepts these properties in the options object. -##### domain - -Specifies the value for the [`Domain` `Set-Cookie` attribute][rfc-6265-5.2.3]. By default, no -domain is set, and most clients will consider the cookie to apply to only the current domain. - ##### encode Specifies a function that will be used to encode a cookie's value. Since value of a cookie @@ -76,86 +71,83 @@ a value into a string suited for a cookie's value. The default function is the global `encodeURIComponent`, which will encode a JavaScript string into UTF-8 byte sequences and then URL-encode any that fall outside of the cookie range. +##### maxAge + +Specifies the `number` (in seconds) to be the value for the [`Max-Age` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.2). +The given number will be converted to an integer by rounding down. By default, no maximum age is set. + +The [cookie storage model specification](https://tools.ietf.org/html/rfc6265#section-5.3) states that if both `expires` and +`maxAge` are set, then `maxAge` takes precedence, but it is possible not all clients by obey this, +so if both are set, they should point to the same date and time. + ##### expires -Specifies the `Date` object to be the value for the [`Expires` `Set-Cookie` attribute][rfc-6265-5.2.1]. +Specifies the `Date` object to be the value for the [`Expires` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.1). By default, no expiration is set, and most clients will consider this a "non-persistent cookie" and will delete it on a condition like exiting a web browser application. -**note** the [cookie storage model specification][rfc-6265-5.3] states that if both `expires` and +The [cookie storage model specification](https://tools.ietf.org/html/rfc6265#section-5.3) states that if both `expires` and `maxAge` are set, then `maxAge` takes precedence, but it is possible not all clients by obey this, so if both are set, they should point to the same date and time. +##### domain + +Specifies the value for the [`Domain` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.3). +By default, no domain is set, and most clients will consider the cookie to apply to only the current domain. + +##### path + +Specifies the value for the [`Path` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.4). By default, the path +is considered the ["default path"](https://tools.ietf.org/html/rfc6265#section-5.1.4). + ##### httpOnly -Specifies the `boolean` value for the [`HttpOnly` `Set-Cookie` attribute][rfc-6265-5.2.6]. When truthy, +Specifies the `boolean` value for the [`HttpOnly` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.6). When truthy, the `HttpOnly` attribute is set, otherwise it is not. By default, the `HttpOnly` attribute is not set. -**note** be careful when setting this to `true`, as compliant clients will not allow client-side +Be careful when setting this to `true`, as compliant clients will not allow client-side JavaScript to see the cookie in `document.cookie`. -##### maxAge +##### secure -Specifies the `number` (in seconds) to be the value for the [`Max-Age` `Set-Cookie` attribute][rfc-6265-5.2.2]. -The given number will be converted to an integer by rounding down. By default, no maximum age is set. +Specifies the `boolean` value for the [`Secure` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.5). When truthy, +the `Secure` attribute is set, otherwise it is not. By default, the `Secure` attribute is not set. -**note** the [cookie storage model specification][rfc-6265-5.3] states that if both `expires` and -`maxAge` are set, then `maxAge` takes precedence, but it is possible not all clients by obey this, -so if both are set, they should point to the same date and time. +Be careful when setting this to `true`, as compliant clients will not send the cookie back to +the server in the future if the browser does not have an HTTPS connection. ##### partitioned -Specifies the `boolean` value for the [`Partitioned` `Set-Cookie`](rfc-cutler-httpbis-partitioned-cookies) +Specifies the `boolean` value for the [`Partitioned` `Set-Cookie`](https://tools.ietf.org/html/draft-cutler-httpbis-partitioned-cookies/) attribute. When truthy, the `Partitioned` attribute is set, otherwise it is not. By default, the `Partitioned` attribute is not set. -**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. - -More information about can be found in [the proposal](https://github.com/privacycg/CHIPS). - -##### path - -Specifies the value for the [`Path` `Set-Cookie` attribute][rfc-6265-5.2.4]. By default, the path -is considered the ["default path"][rfc-6265-5.1.4]. +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. More information +about can be found in [the proposal](https://github.com/privacycg/CHIPS). ##### priority -Specifies the `string` to be the value for the [`Priority` `Set-Cookie` attribute][rfc-west-cookie-priority-00-4.1]. +Specifies the `string` to be the value for the [`Priority` `Set-Cookie` attribute](https://tools.ietf.org/html/draft-west-cookie-priority-00#section-4.1). - `'low'` will set the `Priority` attribute to `Low`. - `'medium'` will set the `Priority` attribute to `Medium`, the default priority when not set. - `'high'` will set the `Priority` attribute to `High`. More information about the different priority levels can be found in -[the specification][rfc-west-cookie-priority-00-4.1]. - -**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. +[the specification](https://tools.ietf.org/html/draft-west-cookie-priority-00#section-4.1). ##### sameSite -Specifies the `boolean` or `string` to be the value for the [`SameSite` `Set-Cookie` attribute][rfc-6265bis-09-5.4.7]. +Specifies the value for the [`SameSite` `Set-Cookie` attribute](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-09#section-5.4.7). - `true` will set the `SameSite` attribute to `Strict` for strict same site enforcement. -- `false` will not set the `SameSite` attribute. - `'lax'` will set the `SameSite` attribute to `Lax` for lax same site enforcement. - `'none'` will set the `SameSite` attribute to `None` for an explicit cross-site cookie. - `'strict'` will set the `SameSite` attribute to `Strict` for strict same site enforcement. More information about the different enforcement levels can be found in -[the specification][rfc-6265bis-09-5.4.7]. - -**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. - -##### secure - -Specifies the `boolean` value for the [`Secure` `Set-Cookie` attribute][rfc-6265-5.2.5]. When truthy, -the `Secure` attribute is set, otherwise it is not. By default, the `Secure` attribute is not set. - -**note** be careful when setting this to `true`, as compliant clients will not send the cookie back to -the server in the future if the browser does not have an HTTPS connection. +[the specification](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-09#section-5.4.7). ## Example @@ -254,21 +246,8 @@ npm run bench ## References -- [RFC 6265: HTTP State Management Mechanism][rfc-6265] -- [Same-site Cookies][rfc-6265bis-09-5.4.7] - -[rfc-cutler-httpbis-partitioned-cookies]: https://tools.ietf.org/html/draft-cutler-httpbis-partitioned-cookies/ -[rfc-west-cookie-priority-00-4.1]: https://tools.ietf.org/html/draft-west-cookie-priority-00#section-4.1 -[rfc-6265bis-09-5.4.7]: https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-09#section-5.4.7 -[rfc-6265]: https://tools.ietf.org/html/rfc6265 -[rfc-6265-5.1.4]: https://tools.ietf.org/html/rfc6265#section-5.1.4 -[rfc-6265-5.2.1]: https://tools.ietf.org/html/rfc6265#section-5.2.1 -[rfc-6265-5.2.2]: https://tools.ietf.org/html/rfc6265#section-5.2.2 -[rfc-6265-5.2.3]: https://tools.ietf.org/html/rfc6265#section-5.2.3 -[rfc-6265-5.2.4]: https://tools.ietf.org/html/rfc6265#section-5.2.4 -[rfc-6265-5.2.5]: https://tools.ietf.org/html/rfc6265#section-5.2.5 -[rfc-6265-5.2.6]: https://tools.ietf.org/html/rfc6265#section-5.2.6 -[rfc-6265-5.3]: https://tools.ietf.org/html/rfc6265#section-5.3 +- [RFC 6265: HTTP State Management Mechanism](https://tools.ietf.org/html/rfc6265) +- [Same-site Cookies](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-09#section-5.4.7) ## License diff --git a/src/index.ts b/src/index.ts index 38b8878..c87c955 100644 --- a/src/index.ts +++ b/src/index.ts @@ -62,6 +62,17 @@ const pathValueRegExp = /^[\u0020-\u003A\u003D-\u007E]*$/; * Parse options. */ export interface ParseOptions { + /** + * Specifies a function that will be used to decode a cookie's value. Since + * the value of a cookie has a limited character set (and must be a simple + * string), this function can be used to decode a previously-encoded cookie + * value into a JavaScript string. + * + * Note: if an error is thrown from this function, the original, non-decoded + * cookie value will be returned as the cookie's value. + * + * @default decodeURIComponent + */ decode?: (str: string) => string; } @@ -143,15 +154,91 @@ function endIndex(str: string, index: number, min: number) { * Serialize options. */ export interface SerializeOptions { + /** + * Specifies a function that will be used to encode a cookie's value. Since + * value of a cookie has a limited character set (and must be a simple string), + * this function can be used to encode a value into a string suited for a cookie's value. + * + * @default encodeURIComponent + */ encode?: (str: string) => string; + /** + * Specifies the `number` (in seconds) to be the value for the [`Max-Age` `Set-Cookie` attribute][rfc-6265-5.2.2]. +The given number will be converted to an integer by rounding down. By default, no maximum age is set. + +The [cookie storage model specification](https://tools.ietf.org/html/rfc6265#section-5.3) states that if both `expires` and +`maxAge` are set, then `maxAge` takes precedence, but it is possible not all clients by obey this, +so if both are set, they should point to the same date and time. + */ maxAge?: number; + /** + * Specifies the `Date` object to be the value for the [`Expires` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.1). + * By default, no expiration is set, and most clients will consider this a "non-persistent cookie" and + * will delete it on a condition like exiting a web browser application. + * + * The [cookie storage model specification](https://tools.ietf.org/html/rfc6265#section-5.3) states that if both `expires` and + * `maxAge` are set, then `maxAge` takes precedence, but it is possible not all clients by obey this, + * so if both are set, they should point to the same date and time. + */ + expires?: Date; + /** + * Specifies the value for the [`Domain` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.3). + * By default, no domain is set, and most clients will consider the cookie to apply to only the current domain. + */ domain?: string; + /** + * Specifies the value for the [`Path` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.4). By default, the path + * is considered the ["default path"](https://tools.ietf.org/html/rfc6265#section-5.1.4). + */ path?: string; - expires?: Date; + /** + * Specifies the `boolean` value for the [`HttpOnly` `Set-Cookie` attribute][rfc-6265-5.2.6]. When truthy, + * the `HttpOnly` attribute is set, otherwise it is not. By default, the `HttpOnly` attribute is not set. + * + * Be careful when setting this to `true`, as compliant clients will not allow client-side + * JavaScript to see the cookie in `document.cookie`. + */ httpOnly?: boolean; + /** + * Specifies the `boolean` value for the [`Secure` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.5). When truthy, + * the `Secure` attribute is set, otherwise it is not. By default, the `Secure` attribute is not set. + * + * Be careful when setting this to `true`, as compliant clients will not send the cookie back to + * the server in the future if the browser does not have an HTTPS connection. + */ secure?: boolean; + /** + * Specifies the `boolean` value for the [`Partitioned` `Set-Cookie`](https://tools.ietf.org/html/draft-cutler-httpbis-partitioned-cookies/) + * attribute. When truthy, the `Partitioned` attribute is set, otherwise it is not. By default, the + * `Partitioned` attribute is not set. + * + * 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. More information + * about can be found in [the proposal](https://github.com/privacycg/CHIPS). + */ partitioned?: boolean; + /** + * Specifies the value for the [`Priority` `Set-Cookie` attribute](https://tools.ietf.org/html/draft-west-cookie-priority-00#section-4.1). + * + * - `'low'` will set the `Priority` attribute to `Low`. + * - `'medium'` will set the `Priority` attribute to `Medium`, the default priority when not set. + * - `'high'` will set the `Priority` attribute to `High`. + * + * More information about the different priority levels can be found in + * [the specification](https://tools.ietf.org/html/draft-west-cookie-priority-00#section-4.1). + */ priority?: "low" | "medium" | "high"; + /** + * Specifies the value for the [`SameSite` `Set-Cookie` attribute](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-09#section-5.4.7). + * + * - `true` will set the `SameSite` attribute to `Strict` for strict same site enforcement. + * - `'lax'` will set the `SameSite` attribute to `Lax` for lax same site enforcement. + * - `'none'` will set the `SameSite` attribute to `None` for an explicit cross-site cookie. + * - `'strict'` will set the `SameSite` attribute to `Strict` for strict same site enforcement. + * + * More information about the different enforcement levels can be found in + * [the specification](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-09#section-5.4.7). + */ sameSite?: boolean | "lax" | "strict" | "none"; }