115 lines
5.9 KiB
TypeScript
115 lines
5.9 KiB
TypeScript
/**
|
|
* Parse options.
|
|
*/
|
|
export interface ParseOptions {
|
|
/**
|
|
* 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`, 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 decode
|
|
*/
|
|
decode?: (str: string) => string | undefined;
|
|
}
|
|
/**
|
|
* Parse a cookie header.
|
|
*
|
|
* Parse the given cookie header string into an object
|
|
* The object has the various cookies as keys(names) => values
|
|
*/
|
|
export declare function parse(str: string, options?: ParseOptions): Record<string, string | undefined>;
|
|
/**
|
|
* Serialize options.
|
|
*/
|
|
export interface SerializeOptions {
|
|
/**
|
|
* 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 [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).
|
|
* 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,
|
|
* 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).
|
|
* 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).
|
|
* When no path is set, the path is considered the ["default path"](https://tools.ietf.org/html/rfc6265#section-5.1.4).
|
|
*/
|
|
path?: string;
|
|
/**
|
|
* 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;
|
|
/**
|
|
* 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;
|
|
/**
|
|
* 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 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 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 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";
|
|
}
|
|
/**
|
|
* Serialize data into a cookie header.
|
|
*
|
|
* Serialize a name value pair into a cookie string suitable for
|
|
* http headers. An optional options object specifies cookie parameters.
|
|
*
|
|
* serialize('foo', 'bar', { httpOnly: true })
|
|
* => "foo=bar; httpOnly"
|
|
*/
|
|
export declare function serialize(name: string, val: string, options?: SerializeOptions): string;
|