Update option documentation (#186)

blakeembrey · web-flow · commit ad9c9601f504 · 2024-10-08T14:32:39.000-07:00
diff --git a/README.md b/README.md
@@ -21,7 +21,7 @@ const cookie = require("cookie");
 
 ### cookie.parse(str, options)
 
-Parse an HTTP `Cookie` header string and returning an object of all cookie name-value pairs.
+Parse a HTTP `Cookie` header string and returning an object of all cookie name-value pairs.
 The `str` argument is the string representing a `Cookie` header value and `options` is an
 optional object containing additional parsing options.
 
@@ -36,15 +36,13 @@ const cookies = cookie.parse("foo=bar; equation=E%3Dmc%5E2");
 
 ##### decode
 
-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
+Specifies a function that will be used to decode a [cookie-value](https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1).
+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.
 
-The default function is the global `decodeURIComponent`, which will decode any URL-encoded
-sequences into their byte representations.
-
-If an error is thrown from this function, the original, non-decoded cookie value will
-be returned as the cookie's value.
+The default function is the global `decodeURIComponent`, wrapped in a `try..catch`. If an error
+is thrown it will return the cookie's original value. If you provide your own encode/decode
+scheme you must ensure errors are appropriately handled.
 
 ### cookie.serialize(name, value, options)
 
@@ -63,17 +61,15 @@ const setCookie = cookie.serialize("foo", "bar");
 
 ##### encode
 
-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.
+Specifies a function that will be used to encode a [cookie-value](https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1).
+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, and should mirror `decode` when parsing.
 
-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.
+The default function is the global `encodeURIComponent`.
 
 ##### 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,
@@ -82,8 +78,7 @@ 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](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.
+When no expiration is set clients consider this a "non-persistent cookie" and delete it the current session is over.
 
 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,
@@ -92,49 +87,41 @@ 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.
+When no domain is set clients consider the cookie to apply to the current domain only.
 
 ##### 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).
+Specifies the value for the [`Path` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.4).
+When no path is set, 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](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.
-
-Be careful when setting this to `true`, as compliant clients will not allow client-side
-JavaScript to see the cookie in `document.cookie`.
+Enables the [`HttpOnly` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.6).
+When enabled, clients will not allow client-side JavaScript to see the cookie in `document.cookie`.
 
 ##### secure
 
-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.
+Enables the [`Secure` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.5).
+When enabled, clients will only send the cookie back if the browser has a HTTPS connection.
 
 ##### partitioned
 
-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.
+Enables the [`Partitioned` `Set-Cookie` attribute](https://tools.ietf.org/html/draft-cutler-httpbis-partitioned-cookies/).
+When enabled, clients will only send the cookie back when the current domain _and_ top-level domain matches.
 
 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
+This also means 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](https://tools.ietf.org/html/draft-west-cookie-priority-00#section-4.1).
+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).
+More information about priority levels can be found in [the specification](https://tools.ietf.org/html/draft-west-cookie-priority-00#section-4.1).
 
 ##### sameSite
 
@@ -145,8 +132,7 @@ Specifies the value for the [`SameSite` `Set-Cookie` attribute](https://tools.ie
 - `'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).
+More information about enforcement levels can be found in [the specification](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-09#section-5.4.7).
 
 ## Example
 
diff --git a/src/index.ts b/src/index.ts
@@ -71,15 +71,15 @@ const NullObject = /* @__PURE__ */ (() => {
  */
 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.
+   * Specifies a function that will be used to decode a [cookie-value](https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1).
+   * 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.
+   * The default function is the global `decodeURIComponent`, wrapped in a `try..catch`. If an error
+   * is thrown it will return the cookie's original value. If you provide your own encode/decode
+   * scheme you must ensure errors are appropriately handled.
    *
-   * @default decodeURIComponent
+   * @default decode
    */
   decode?: (str: string) => string | undefined;
 }
@@ -155,16 +155,15 @@ function endIndex(str: string, index: number, min: number) {
  */
 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.
+   * Specifies a function that will be used to encode a [cookie-value](https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1).
+   * 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, and should mirror `decode` when parsing.
    *
    * @default encodeURIComponent
    */
   encode?: (str: string) => string;
   /**
    * 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,
@@ -173,8 +172,7 @@ export interface SerializeOptions {
   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.
+   * When no expiration is set clients consider this a "non-persistent cookie" and delete it the current session is over.
    *
    * 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,
@@ -183,37 +181,30 @@ export interface SerializeOptions {
   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.
+   * When no domain is set clients consider the cookie to apply to the current domain only.
    */
   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).
+   * Specifies the value for the [`Path` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.4).
+   * When no path is set, the path is considered the ["default path"](https://tools.ietf.org/html/rfc6265#section-5.1.4).
    */
   path?: string;
   /**
-   * 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`.
+   * Enables the [`HttpOnly` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.6).
+   * When enabled, 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.
+   * Enables the [`Secure` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.5).
+   * When enabled, clients will only send the cookie back if the browser has a 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.
+   * Enables the [`Partitioned` `Set-Cookie` attribute](https://tools.ietf.org/html/draft-cutler-httpbis-partitioned-cookies/).
+   * When enabled, clients will only send the cookie back when the current domain _and_ top-level domain matches.
    *
    * 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
+   * This also means 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;
@@ -224,8 +215,7 @@ export interface SerializeOptions {
    * - `'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).
+   * More information about 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";
   /**
@@ -236,8 +226,7 @@ export interface SerializeOptions {
    * - `'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).
+   * More information about 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";
 }
