\n\n## Table of Contents\n\n- [Getting started](#getting-started)\n - [Installation](#installation)\n - [Usage](#usage)\n - [Cookie](#cookie)\n - [Parsing cookie](#parsing-cookie)\n - [Translators](#translators)\n - [Statistics](#statistics)\n - [Tracing](#tracing)\n - [Validating cookie](#validating-cookie)\n - [Serializing cookie](#serializing-cookie)\n - [Set-Cookie](#set-cookie)\n - [Parsing Set-Cookie](#parsing-set-cookie)\n - [Validating Set-Cookie](#validating-set-cookie)\n - [Serializing Set-Cookie](#serializing-set-cookie)\n - [Encoders](#encoders)\n - [Generic encoders](#generic-encoders)\n - [Cookie Name encoders](#cookie-name-encoders)\n - [Cookie Value encoders](#cookie-value-encoders)\n - [Decoders](#decoders)\n - [Generic decoders](#generic-decoders)\n - [Cookie Name decoders](#cookie-name-decoders)\n - [Cookie Value decoders](#cookie-value-decoders)\n - [Validators](#validators)\n - [Cookie Name validators](#cookie-name-validators)\n - [Cookie Value validators](#cookie-value-validators)\n - [Errors](#errors)\n - [Grammar](#grammar)\n- [More about RFC 6265](#more-about-rfc-6265)\n- [License](#license)\n\n## Getting started\n\n### Installation\n\nYou can install `@swaggerexpert/cookie` using `npm`:\n\n```sh\n $ npm install @swaggerexpert/cookie\n```\n\n---\n\n**[unpkg.com](https://unpkg.com/)**\n\nInclude following script tag into your HTML file:\n\n```html\n\n```\n\nGlobal variable `SwaggerExpertCookie` will be available in the browser matching interface of `@swaggerexpert/cookie` npm package.\n`cookie.browser.min.js` is [UMD](https://github.com/umdjs/umd?tab=readme-ov-file#umd-universal-module-definition) minified build artifact.\nThere is also unminified `cookie.browser.js` artifact, suitable for debugging.\nThe browser artifacts target the latest browsers; they can also be loaded via `require` in Node.js >= 16.\n\n---\n\n**[jsDelivr](https://www.jsdelivr.com/)**\n\nInclude following script tag into your HTML file (ESM mode):\n\n```html\n\n```\nLocal variable `SwaggerExpertCookie` will be available in scope of the `\n```\n\nGlobal variable `SwaggerExpertCookie` will be available in the browser matching interface of `@swaggerexpert/cookie` npm package.\n`cookie.browser.min.js` is [UMD](https://github.com/umdjs/umd?tab=readme-ov-file#umd-universal-module-definition) minified build artifact.\nThere is also unminified `cookie.browser.js` artifact, suitable for debugging.\n\n### Usage\n\n`@swaggerexpert/cookie` currently supports **parsing**, **validation** and **serialization**.\nParser is based on a superset of [ABNF](https://www.rfc-editor.org/rfc/rfc5234) ([SABNF](https://cs.github.com/ldthomas/apg-js2/blob/master/SABNF.md))\nand uses [apg-lite](https://github.com/ldthomas/apg-lite) parser generator.\n\n#### Cookie\n\nThe `Cookie` header is an HTTP header used to send cookies from the client (e.g., a browser) to the server.\nThe `Cookie` header is sent in HTTP requests and contains one or more cookies that the server previously set\nvia the `Set-Cookie` header. Cookies are formatted as key-value pairs, separated by semicolons (`;`),\nand do not include metadata like `Path`, `Domain`, or `HttpOnly`.\n\n##### Parsing Cookie\n\nParsing a cookie is as simple as importing the **parseCookie** function and calling it.\n\n```js\nimport { parseCookie } from '@swaggerexpert/cookie';\n\nconst parseResult = parseCookie('foo=bar');\nparseResult.result.success; // => true\n```\n\nThe **lenient** mode for cookie parsing is designed to handle and extract valid\ncookie-pairs from potentially malformed or non-standard cookie strings.\nIt focuses on maintaining compatibility with real-world scenarios where cookie\nheaders may deviate from strict compliance with RFC 6265.\n\n```js\nimport { parseCookie } from '@swaggerexpert/cookie';\n\n/**\n * All of the following parse successfully.\n */\n\nparseCookie('foo1=bar; foo2=baz', { strict: false });\nparseCookie('foo1=bar;foo2=baz', { strict: false });\nparseCookie('FOO = bar; baz = raz', { strict: false });\nparseCookie('foo=\"bar=123456789&name=Magic+Mouse\"', { strict: false });\nparseCookie('foo = \"bar\"', { strict: false });\nparseCookie('foo = bar ; fizz = buzz', { strict: false });\nparseCookie('foo =', { strict: false });\nparseCookie('\\tfoo\\t=\\tbar\\t', { strict: false });\nparseCookie('foo1=bar;foo2=baz', { strict: false });\nparseCookie('foo1=bar; foo2=baz', { strict: false });\nparseCookie('foo=bar; fizz; buzz', { strict: false });\nparseCookie('fizz; buzz; foo=bar', { strict: false });\nparseCookie('name=name=3', { strict: false });\nparseCookie('name:name=3', { strict: false });\n```\n\n**parseResult** variable has the following shape:\n\n```\n{\n result: ,\n tree: ,\n stats: ,\n trace: ,\n}\n```\n\n[TypeScript typings](https://github.com/swaggerexpert/cookie/blob/main/types/index.d.ts) are available for all fields attached to parse result object returned by the `parseCookie` function.\n\n###### Translators\n\n`@swaggerexpert/cookie` provides several translators to convert the parse result into different tree representations.\nTranslators produce the same node types in both strict and lenient mode.\n\n**CST translator**\n\n[Concrete Syntax Tree](https://en.wikipedia.org/wiki/Parse_tree) (Parse tree) representation is available on parse result\nwhen instance of `CSTTranslator` is provided via a `translator` option to the `parseCookie` function.\nCST is suitable to be consumed by other tools like IDEs, editors, etc...\n\n```js\nimport { parseCookie, CSTTranslator } from '@swaggerexpert/cookie';\n\nconst { tree: cst } = parseCookie('foo=bar', { translator: new CSTTranslator() });\n```\n\nCST tree has a shape documented by [TypeScript typings (CSTNode)](https://github.com/swaggerexpert/cookie/blob/main/types/index.d.ts).\n\n**AST translator**\n\n**Default translator**. [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) representation is available on parse result\nby default or when instance of `ASTTranslator` is provided via a `translator` option to the `parseCookie` function.\n\n```js\nimport { parseCookie } from '@swaggerexpert/cookie';\n\nconst { tree: ast } = parseCookie('foo=bar; baz=\"raz\"');\n```\n\nor\n\n```js\nimport { parseCookie, ASTTranslator } from '@swaggerexpert/cookie';\n\nconst { tree: ast } = parseCookie('foo=bar; baz=\"raz\"', { translator: new ASTTranslator() });\n```\n\nAfter running the above code, **ast** variable has the following shape:\n\n```js\n{\n type: 'CookieString',\n pairs: [\n { type: 'CookiePair', name: 'foo', value: 'bar' },\n { type: 'CookiePair', name: 'baz', value: '\"raz\"' },\n ],\n}\n```\n\nCookie values are raw, exactly as they appear in the cookie string (including the surrounding DQUOTEs, if present).\nAST tree has a shape documented by [TypeScript typings (ASTNode)](https://github.com/swaggerexpert/cookie/blob/main/types/index.d.ts).\n\n**List translator**\n\nList of entries representation is available on parse result\nwhen instance of `ListTranslator` is provided via a `translator` option to the `parseCookie` function.\nEvery entry is a `[type, text]` tuple, ordered as matched by the parser.\n\n```js\nimport { parseCookie, ListTranslator } from '@swaggerexpert/cookie';\n\nconst { tree: list } = parseCookie('foo=bar', { translator: new ListTranslator() });\n```\n\nAfter running the above code, **list** variable has the following shape:\n\n```js\n[\n ['cookie-string', 'foo=bar'],\n ['cookie-pair', 'foo=bar'],\n ['cookie-name', 'foo'],\n ['cookie-value', 'bar'],\n]\n```\n\n> NOTE: for backward compatibility, parse result also exposes the deprecated `ast` field,\n> regardless of the translator used. `parseResult.ast.translate(parts)` populates `parts` with the same list of entries\n> as `ListTranslator` produces, and `parseResult.ast.toXml()` returns XML representation. Prefer translators in new code.\n\n**Object translator**\n\nObject representation, mapping cookie names to cookie values, is available on parse result\nwhen instance of `ObjectTranslator` is provided via a `translator` option to the `parseCookie` function.\n\n```js\nimport { parseCookie, ObjectTranslator } from '@swaggerexpert/cookie';\n\nconst { tree: cookies } = parseCookie('foo=bar; baz=raz; foo=boo', { translator: new ObjectTranslator() });\n// => { foo: 'bar', baz: 'raz' }\n```\n\nWhen a cookie name appears multiple times, the first cookie value wins. This is a convention: user agents SHOULD send cookies\nwith longer paths first ([RFC 6265, Section 5.4](https://datatracker.ietf.org/doc/html/rfc6265#section-5.4)), but servers\nSHOULD NOT rely on the order ([RFC 6265, Section 4.2.2](https://datatracker.ietf.org/doc/html/rfc6265#section-4.2.2)).\nUse [entries translator](#translators) or the AST to access all cookie pairs.\n\nThe object has `null` prototype, so cookie names like `__proto__` or `constructor` are plain own properties,\nand lookups of absent cookie names (e.g. `cookies.toString`) are `undefined`. Order of the object keys follows\nJavaScript property order, i.e. integer-like cookie names come first; use entries translator when the order matters.\n\nAs the object doesn't inherit from `Object.prototype`:\n\n- use `Object.prototype.hasOwnProperty.call(cookies, name)` or `name in cookies` instead of `cookies.hasOwnProperty(name)`\n- converting the object to a string (`String(cookies)`, template literals) throws `TypeError`\n- use spread (`{ ...cookies }`) to get a plain object; `Object.assign({}, cookies)` would drop a cookie named `__proto__`\n- strict deep equality with plain objects (e.g. `assert.deepStrictEqual`) fails; compare `{ ...cookies }` instead\n\n`ObjectTranslator` accepts the same `decoders` option as `ASTTranslator`:\n\n```js\nimport { parseCookie, ObjectTranslator, cookieValueRotatingDecoder } from '@swaggerexpert/cookie';\n\nconst translator = new ObjectTranslator({ decoders: { value: cookieValueRotatingDecoder } });\nparseCookie('foo=Ow; bar=aGVsbG8', { translator }).tree; // => { foo: ';', bar: 'hello' }\n```\n\n**Entries translator**\n\nList of `[name, value]` entries, in order of appearance, is available on parse result\nwhen instance of `EntriesTranslator` is provided via a `translator` option to the `parseCookie` function.\nUnlike the [object translator](#translators), all cookie pairs are retained, including duplicate cookie names.\n\n```js\nimport { parseCookie, serializeCookie, EntriesTranslator } from '@swaggerexpert/cookie';\n\nconst { tree: entries } = parseCookie('foo=bar; baz=raz; foo=boo', { translator: new EntriesTranslator() });\n// => [['foo', 'bar'], ['baz', 'raz'], ['foo', 'boo']]\n\nserializeCookie(entries); // => 'foo=bar; baz=raz; foo=boo'\n```\n\nCookie strings parsed in strict mode are serialized back to the same cookie string. Cookie strings parsed in [lenient](#parsing-cookie) mode\ncan contain cookie names and values which the default [encoders](#encoders) and [validators](#validators) of `serializeCookie` re-encode or reject.\nUse identity value encoder and lenient validators to serialize the parsed cookie names and values without modification.\nThe resulting cookie string contains the same cookie pairs, but is not necessarily identical: whitespace around cookie names and values\nis not retained, entries without `=` are dropped (a cookie string consisting only of such entries results in an empty string),\nand separators are normalized to `\"; \"`:\n\n```js\nimport {\n parseCookie,\n serializeCookie,\n EntriesTranslator,\n identity,\n cookieNameLenientValidator,\n cookieValueLenientValidator,\n} from '@swaggerexpert/cookie';\n\nconst { tree: entries } = parseCookie('a=\"b c\";x(y=b\\\\c', { strict: false, translator: new EntriesTranslator() });\n\nserializeCookie(entries, {\n encoders: { value: identity },\n validators: { name: cookieNameLenientValidator, value: cookieValueLenientValidator },\n}); // => 'a=\"b c\"; x(y=b\\\\c'\n```\n\n`EntriesTranslator` accepts the same `decoders` option as `ASTTranslator`.\nWhen cookie names or values are decoded, serializing them doesn't necessarily reproduce the original cookie string:\n[encoders](#encoders) leave values that are already valid untouched (e.g. `a=YWJj` decoded by `cookieValueBase64Decoder` to `abc`\nis serialized as `a=abc`, even with `cookieValueStrictBase64Encoder`).\n\n**XML translator**\n\n```js\nimport { parseCookie, XMLTranslator } from '@swaggerexpert/cookie';\n\nconst { tree: xml } = parseCookie('foo=bar', { translator: new XMLTranslator() });\n```\n\n**No translator**\n\nWhen only validity of the cookie string matters, translation can be skipped by setting `translator` option to `null`.\n\n```js\nimport { parseCookie } from '@swaggerexpert/cookie';\n\nconst { result, tree } = parseCookie('foo=bar', { translator: null });\nresult.success; // => true\ntree; // => undefined\n```\n\n###### Statistics\n\n`parseCookie` function returns additional statistical information about the parsing process.\nCollection of the statistics can be enabled by setting `stats` option to `true`.\n\n```js\nimport { parseCookie } from '@swaggerexpert/cookie';\n\nconst { stats } = parseCookie('foo=bar', { stats: true });\n\nstats.displayStats(); // returns operator statistics as string\nstats.displayHits(); // returns rules grouped by hit count as string\n```\n\n###### Tracing\n\n`parseCookie` function returns additional tracing information about the parsing process.\nTracing can be enabled by setting `trace` option to `true`. Tracing is essential\nfor debugging failed parses or analyzing rule execution flow.\n\n```js\nimport { parseCookie } from '@swaggerexpert/cookie';\n\nconst { result, trace } = parseCookie('foo', { trace: true });\n\nresult.success; // false\ntrace.displayTrace(); // returns trace information as string\n```\n\nTracing also allows you to infer expected tokens at a failure point. This is useful for generating meaningful syntax error messages.\n\n```js\nimport { parseCookie } from '@swaggerexpert/cookie';\n\nconst { trace } = parseCookie('foo', { trace: true });\n\nconst expectations = trace.inferExpectations();\nexpectations.includes('='); // => true\n```\n\n##### Validating Cookie\n\nValidating a cookie string is as simple as importing the **testCookie** function and calling it.\n\n```js\nimport { testCookie } from '@swaggerexpert/cookie';\n\ntestCookie('foo=bar'); // => true\ntestCookie('foo=bar; baz=raz'); // => true\ntestCookie('foo=bar;baz=raz'); // => false (missing SP after semicolon)\ntestCookie('foo=bar;baz=raz', { strict: false }); // => true\n```\n\nIndividual cookie names and values can be validated as well, using **testCookieName** and **testCookieValue** functions.\nThis is useful, for example, for validating `name` of [OpenAPI Parameter Objects](https://spec.openapis.org/oas/latest.html#parameter-object)\nlocated in a cookie (`in: cookie`), which must be a valid cookie name in order to be sent in the `Cookie` header.\n\n```js\nimport { testCookieName, testCookieValue } from '@swaggerexpert/cookie';\n\ntestCookieName('session_id'); // => true\ntestCookieName('session id'); // => false (SP is not allowed)\ntestCookieName('a:b'); // => false\ntestCookieName('a:b', { strict: false }); // => true\n\ntestCookieValue('bar'); // => true\ntestCookieValue('\"bar\"'); // => true\ntestCookieValue('\"bar\"', { quoted: false }); // => false (must not be enclosed in DQUOTEs)\ntestCookieValue('bar', { quoted: true }); // => false (must be enclosed in DQUOTEs)\ntestCookieValue('b r'); // => false (SP is not allowed)\n```\n\n##### Serializing Cookie\n\nSerializing a cookie is as simple as importing the **serializeCookie** function and calling it.\n\n**Serializing object**:\n\n```js\nimport { serializeCookie } from '@swaggerexpert/cookie';\n\nserializeCookie({ foo: 'bar' }); // => 'foo=bar'\nserializeCookie({ foo: 'bar', baz: 'raz' }); // => 'foo=bar; baz=raz'\n```\n\n**Serializing entries**:\n\nBy using entries (list of key-value pairs), this function supports creating cookies\nwith duplicate names—a common scenario when sending multiple values for the same cookie name.\n\n```js\nimport { serializeCookie } from '@swaggerexpert/cookie';\n\nserializeCookie([['foo', 'bar']]); // => 'foo=bar'\nserializeCookie([[ 'foo', 'bar'], ['baz', 'raz' ]]); // => 'foo=bar; baz=raz'\nserializeCookie([[ 'foo', 'bar'], ['baz', 'raz' ], ['foo', 'boo']]); // => 'foo=bar; baz=raz; foo=boo'\n```\n\n**Options**\n\nThe `serializeCookie` function provides a powerful and flexible API for serializing cookies,\nenabling the implementation of various scenarios. By default, it uses a set of sensible options\nto ensure compliance with cookie standards. However, its behavior can be customized by overriding these defaults.\n\n**Default Options**\n\n[Encoders](#encoders) transform cookie names and values during serialization to ensure they meet encoding requirements.\n[Validators](#validators) ensure that cookie names and values conform to the required standards. If validation fails, an error is thrown.\nValidators are executed **after** encoders, ensuring that values are first transformed before being validated.\n\nThe default options for `serializeCookie` ensure strict compliance with cookie standards by applying\nno encoding for cookie names, RFC compliant encoding for values, and robust validation for\nboth names and values according to [RFC 6265](https://datatracker.ietf.org/doc/html/rfc6265).\n\n```js\n{\n encoders: {\n name: identity,\n value: cookieValueStrictBase64urlEncoder\n },\n validators: {\n name: cookieNameStrictValidator,\n value: cookieValueStrictValidator,\n }\n}\n```\n\n**Customizing serialization**\n\nYou can customize `serializeCookie` behavior by providing your own [encoders](#encoders) or [validators](#validators):\n\n```js\nimport { serializeCookie } from '@swaggerexpert/cookie';\n\nserializeCookie({ foo: 'bar' }, {\n encoders: {\n name: (name) => name.toUpperCase(), // custom name encoder\n value: (value) => encodeURIComponent(value), // custom value encoder\n },\n validators: {\n name: (name) => {\n if (!/^[a-zA-Z]+$/.test(name)) {\n throw new TypeError('Custom validation failed for cookie name');\n }\n },\n value: (value) => {\n if (value.includes(';')) {\n throw new TypeError('Custom validation failed for cookie value');\n }\n },\n },\n});\n```\n\nCompletely **bypassing** encoding and validation is possible as well:\n\n```js\nimport { serializeCookie, identity, noop } from '@swaggerexpert/cookie';\n\nserializeCookie({ foo: ';' }, {\n encoders: { name: identity, value: identity },\n validators: { name: noop, value: noop },\n}); // => \"foo=;\"\n```\n\n#### Set-Cookie\n\nThe `Set-Cookie` header is an HTTP header used to send cookies from the server to the client (e.g., a browser).\nEach `Set-Cookie` header contains a single cookie formatted as key-value pair.\n\n##### Parsing Set-Cookie\n\nParsing a `Set-Cookie` header is as simple as importing the **parseSetCookie** function and calling it.\n\n```js\nimport { parseSetCookie } from '@swaggerexpert/cookie';\n\nconst { result, tree } = parseSetCookie(\n 'id=a3fWa; Expires=Thu, 21 Oct 2027 07:28:00 GMT; Max-Age=3600; Domain=example.com; Path=/docs; Secure; HttpOnly; SameSite=Lax; Foo=bar',\n);\nresult.success; // => true\n```\n\nAfter running the above code, **tree** variable has the following shape:\n\n```js\n{\n type: 'SetCookie',\n name: 'id',\n value: 'a3fWa',\n attributes: {\n expires: new Date('2027-10-21T07:28:00.000Z'),\n maxAge: 3600,\n domain: 'example.com',\n path: '/docs',\n secure: true,\n httpOnly: true,\n sameSite: 'lax',\n },\n extensions: [{ type: 'CookieAttribute', name: 'Foo', value: 'bar' }],\n}\n```\n\nRecognized `attributes` are interpreted following [RFC 6265, Section 5.2](https://datatracker.ietf.org/doc/html/rfc6265#section-5.2):\n\n- attribute names are matched case-insensitively\n- `Expires` is parsed using the [cookie-date](https://datatracker.ietf.org/doc/html/rfc6265#section-5.1.1) algorithm, which recognizes various date formats (e.g. `Wednesday, 21-Oct-15 07:28:00 GMT`)\n- `Max-Age` is an integer, zero and negative values included\n- `Domain` is lower-cased and leading `.` is removed\n- `Path` not starting with `/` resets the path to default-path, which depends on the request URI, and is therefore omitted\n- `Domain` that is empty after removing leading `.` (e.g. `Domain=.`) means host-only cookie, and is therefore omitted\n- `Max-Age` beyond safe integer range is clamped to `Number.MAX_SAFE_INTEGER` (or `Number.MIN_SAFE_INTEGER`)\n- attributes with values that cannot be processed (e.g. `Max-Age=1.5`, `Expires=invalid`) are ignored\n- when an attribute appears multiple times, the last one wins\n- `SameSite`, `Partitioned` and `Priority` are recognized as well, although not part of RFC 6265\n\nUnrecognized attributes are collected in `extensions`, in order of appearance.\nThe shape of `attributes` matches the [attribute options](#serializing-set-cookie) of `serializeSetCookie`, so parsed `Set-Cookie` header can be serialized back:\n\n```js\nimport { parseSetCookie, serializeSetCookie } from '@swaggerexpert/cookie';\n\nconst { tree } = parseSetCookie('id=a3fWa; Max-Age=3600; Path=/; HttpOnly');\nserializeSetCookie(tree.name, tree.value, tree.attributes); // => 'id=a3fWa; Max-Age=3600; Path=/; HttpOnly'\n```\n\nThe **lenient** mode follows parsing algorithm of [RFC 6265, Section 5.2](https://datatracker.ietf.org/doc/html/rfc6265#section-5.2),\nwhich is how user agents parse `Set-Cookie` headers. Whitespace around names and values is ignored, attributes don't have to be separated by `\"; \"`,\nand cookie name and value can contain any characters except CTLs and `;`.\nCTLs (except HTAB) are rejected anywhere in the `Set-Cookie` string, as they are not allowed in [HTTP field values](https://www.rfc-editor.org/rfc/rfc9110#section-5.5).\n\n```js\nimport { parseSetCookie } from '@swaggerexpert/cookie';\n\nparseSetCookie('id=a3fWa;Secure').result.success; // => false\nparseSetCookie('id=a3fWa;Secure', { strict: false }).result.success; // => true\n\nparseSetCookie(' id = a b ; max-age=60 ;HTTPONLY', { strict: false }).tree;\n// => { type: 'SetCookie', name: 'id', value: 'a b', attributes: { maxAge: 60, httpOnly: true }, extensions: [] }\n```\n\n`parseSetCookie` supports the same `decoders`, `translator`, `stats` and `trace` options as [parseCookie](#parsing-cookie).\nTranslators produce `set-cookie-string`, `cookie-pair`, `cookie-name`, `cookie-value` and `cookie-av` nodes in both strict and lenient mode.\n\n##### Validating Set-Cookie\n\n```js\nimport { testSetCookie } from '@swaggerexpert/cookie';\n\ntestSetCookie('id=a3fWa; Path=/; Secure'); // => true\ntestSetCookie('id=a3fWa;Secure'); // => false\ntestSetCookie('id=a3fWa;Secure', { strict: false }); // => true\ntestSetCookie('id'); // => false\n```\n\n##### Serializing Set-Cookie\n\nSerializing a single cookie pair for the `Set-Cookie` header is as simple as importing the **serializeSetCookie** function and calling it.\n\n```js\nimport { serializeSetCookie } from '@swaggerexpert/cookie';\n\nserializeSetCookie('foo', 'bar'); // => 'foo=bar'\nserializeSetCookie('foo', ';'); // => 'foo=Ow' (base64url encoding)\n```\n\n`serializeSetCookie` accepts the same [options](#serializing-cookie) as `serializeCookie`, with the same defaults:\n\n```js\nimport { serializeSetCookie, cookieValueStrictPercentEncoder } from '@swaggerexpert/cookie';\n\nserializeSetCookie('foo', 'b r', {\n encoders: { value: cookieValueStrictPercentEncoder },\n}); // => 'foo=b%20r'\n```\n\n**Attributes**\n\n[Set-Cookie attributes](https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.2) are provided as options:\n\n```js\nimport { serializeSetCookie } from '@swaggerexpert/cookie';\n\nserializeSetCookie('id', 'a3fWa', {\n expires: new Date(Date.UTC(2027, 9, 21, 7, 28)),\n maxAge: 3600,\n domain: 'example.com',\n path: '/docs',\n secure: true,\n httpOnly: true,\n sameSite: 'lax',\n partitioned: true,\n priority: 'high',\n});\n// => 'id=a3fWa; Expires=Thu, 21 Oct 2027 07:28:00 GMT; Max-Age=3600; Domain=example.com; Path=/docs; Secure; HttpOnly; SameSite=Lax; Partitioned; Priority=High'\n```\n\n| Option | Type | Attribute |\n|---|---|---|\n| `expires` | `Date` | [`Expires`](https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.2.1), serialized as `rfc1123-date` |\n| `maxAge` | integer (seconds) | [`Max-Age`](https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.2.2) |\n| `domain` | `string` | [`Domain`](https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.2.3), must be a valid subdomain ([RFC 1034](https://datatracker.ietf.org/doc/html/rfc1034#section-3.5), [RFC 1123](https://datatracker.ietf.org/doc/html/rfc1123#section-2.1)) |\n| `path` | `string` | [`Path`](https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.2.4), any CHAR except CTLs or `;` |\n| `secure` | `boolean` | [`Secure`](https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.2.5) |\n| `httpOnly` | `boolean` | [`HttpOnly`](https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.2.6) |\n| `sameSite` | `'strict'` \\| `'lax'` \\| `'none'` | [`SameSite`](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis#section-4.1.2.7) |\n| `partitioned` | `boolean` | [`Partitioned`](https://datatracker.ietf.org/doc/html/draft-cutler-httpbis-partitioned-cookies) |\n| `priority` | `'low'` \\| `'medium'` \\| `'high'` | [`Priority`](https://datatracker.ietf.org/doc/html/draft-west-cookie-priority-00#section-4.1) |\n\nAttribute values are validated and `TypeError` is thrown when invalid. `SameSite`, `Partitioned` and `Priority` are not part of RFC 6265\nand are serialized as `extension-av`. Option values of `sameSite` and `priority` are case-insensitive.\n\n> NOTE: RFC 6265 grammar requires `Max-Age` to be a non-zero positive integer, but [user agent processing](https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.2)\n> defines zero and negative values as immediate expiration, which is the common way of deleting a cookie. Therefore, any integer is allowed.\n> Similarly, leading `.` in `domain` is tolerated, as it is [ignored by user agents](https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.3).\n\nAttributes are never part of the `Cookie` header; `serializeCookie` ignores them.\n\n#### Encoders\n\nThe `@swaggerexpert/cookie` library provides a suite of encoders designed to handle cookie names and values during **serialization**.\nEach encoder adheres to specific rules for encoding characters, ensuring compatibility with cookie-related standards.\nBelow is a detailed overview of the available encoders.\n\n##### Generic Encoders\n\nGeneric encoders can be used both for cookie names and values.\n\n**base64**\n\nEncodes a string using the [Base64](https://datatracker.ietf.org/doc/html/rfc4648) algorithm. Base64 encoding\nis explicitly mentioned in [RFC 6265, section 4.1.1](https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1) as an example of appropriate encoding for cookie values.\n\n```js\nimport { base64Encoder } from '@swaggerexpert/cookie';\n\nbase64Encoder('foo<'); // => 'Zm9vPA=='\n```\n\n**base64url**\n\nEncodes a string using the [base64url](https://datatracker.ietf.org/doc/html/rfc4648#section-5) algorithm.\nThis encoding consists of Base64 Encoding with URL and Filename Safe Alphabet.\n\n```js\nimport { base64urlEncoder } from '@swaggerexpert/cookie';\n\nbase64urlEncoder('foo<'); // => 'Zm9vPA'\n```\n\n##### Cookie Name Encoders\n\n**cookieNameStrictPercentEncoder**\n\nPercent-encodes characters that fall outside the allowable set defined by the `cookie-name` rule in [RFC 6265](https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1).\n\n- **Use Case**: Ensures that the cookie name strictly adheres to the `cookie-name` non-terminal rule.\n\n```js\nimport { cookieNameStrictPercentEncoder } from '@swaggerexpert/cookie';\n\ncookieNameStrictPercentEncoder('foo<'); // => 'foo%3C'\n```\n\n**cookieNameLenientPercentEncoder**\n\nPercent-encodes characters that fall outside the allowable set defined by the `lenient-cookie-name` rule.\nThis allows for a more lenient interpretation of cookie names.\n\n- **Use Case**: Useful in scenarios where broader compatibility is required, or when leniency in cookie names is acceptable.\n\n```js\nimport { cookieNameLenientPercentEncoder } from '@swaggerexpert/cookie';\n\ncookieNameLenientPercentEncoder('foo<'); // => 'foo<'\n```\n\n##### Cookie Value Encoders\n\n**cookieValueStrictBase64Encoder**\n\nApplies [Base64](https://datatracker.ietf.org/doc/html/rfc4648) encoding to a cookie value if any of its characters fall outside the allowable set defined by the `cookie-value` rule in [RFC 6265](https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1).\n\n- **Use Case**: To achieve the best compatibility, Base64 encoding is mentioned by RFC 6265 as an example of appropriate encoding to use. Ensures strict compliance with the `cookie-value` non-terminal rule.\n\n```js\nimport { cookieValueStrictBase64Encoder } from '@swaggerexpert/cookie';\n\ncookieValueStrictBase64Encoder(';'); // => Ow==\ncookieValueStrictBase64Encoder('\";\"'); // => \"Ow==\"\n```\n\n**cookieValueStrictBase64urlEncoder**\n\nApplies [base64url](https://datatracker.ietf.org/doc/html/rfc4648#section-5) encoding to a cookie value if any of its characters fall outside the allowable set defined by the `cookie-value` rule in [RFC 6265](https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1).\n\n- **Use Case**: More appropriate for modern tooling, it ensures strict compliance with the `cookie-value` non-terminal rule by producing encoded value with URL and Filename Safe Alphabet.\n\n```js\nimport { cookieValueStrictBase64Encoder } from '@swaggerexpert/cookie';\n\ncookieValueStrictBase64Encoder(';'); // => Ow\ncookieValueStrictBase64Encoder('\";\"'); // => \"Ow\"\n```\n\n**cookieValueStrictPercentEncoder**\n\nPercent-encodes characters that fall outside the allowable set defined by the `cookie-value` rule in [RFC 6265](https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1).\n\n- **Use Case**: Ensures strict compliance with the `cookie-value` non-terminal rule, encoding characters such as `;` and `,`.\n\n```js\nimport { cookieValueStrictPercentEncoder } from '@swaggerexpert/cookie';\n\ncookieValueStrictPercentEncoder(';'); // => '%3B'\n```\n\n**cookieValueLenientBase64Encoder**\n\nApplies [Base64](https://datatracker.ietf.org/doc/html/rfc4648) encoding to a cookie value if any of its characters fall outside the allowable set defined by the `lenient-cookie-value`.\n\n- **Use Case**: To achieve the best compatibility, Base64 encoding is mentioned by RFC 6265 as an example of appropriate encoding to use. Useful when broader compatibility is needed, and when leniency in cookie values is acceptable.\n\n```js\nimport { cookieValueLenientBase64Encoder } from '@swaggerexpert/cookie';\n\ncookieValueLenientBase64Encoder(';'); // => Ow==\ncookieValueLenientBase64Encoder('\";\"'); // => \"Ow==\"\n```\n\n**cookieValueLenientBase64urlEncoder**\n\nApplies [base64url](https://datatracker.ietf.org/doc/html/rfc4648#section-5) encoding to a cookie value if any of its characters fall outside the allowable set defined by the `lenient-cookie-value`.\n\n- **Use Case**: More appropriate for modern tooling. Useful when producing encoded value with URL and Filename Safe Alphabet, and leniency in cookie values is acceptable.\n-\n\n```js\nimport { cookieValueLenientBase64urlEncoder } from '@swaggerexpert/cookie';\n\ncookieValueLenientBase64urlEncoder(';'); // => Ow\ncookieValueLenientBase64urlEncoder('\";\"'); // => \"Ow\"\n```\n\n**cookieValueLenientPercentEncoder**\n\nPercent-encodes characters that fall outside the allowable set defined by the `lenient-cookie-value` rule.\nThis allows for a more permissive interpretation of cookie values.\n\n- **Use Case**: Useful when broader compatibility is needed, and when leniency in cookie values is acceptable.\n\n```js\nimport { cookieValueLenientPercentEncoder } from '@swaggerexpert/cookie';\n\ncookieValueLenientPercentEncoder('\"'); // => '\"'\n```\n\n#### Decoders\n\nDecoders are the counterpart of [encoders](#encoders), designed to recover original cookie names and values during **parsing**.\nThey can be provided to the `parseCookie` function via `decoders` option and are applied to the cookie names and values\nof the [AST](#translators). By default, no decoding is performed and cookie names and values are returned as they appear in the cookie string.\n\n```js\nimport { parseCookie, cookieNamePercentDecoder, cookieValueBase64urlDecoder } from '@swaggerexpert/cookie';\n\nconst { tree } = parseCookie('foo%20bar=Ow', {\n decoders: {\n name: cookieNamePercentDecoder,\n value: cookieValueBase64urlDecoder,\n },\n});\n// tree.pairs => [{ type: 'CookiePair', name: 'foo bar', value: ';' }]\n```\n\nWhen a custom translator is used, decoders are provided to the `ASTTranslator` directly:\n\n```js\nimport { parseCookie, ASTTranslator, cookieValueBase64urlDecoder } from '@swaggerexpert/cookie';\n\nconst translator = new ASTTranslator({ decoders: { value: cookieValueBase64urlDecoder } });\nconst { tree } = parseCookie('foo=Ow', { translator });\n```\n\nDecoders throw `TypeError` if the input is not properly encoded (invalid alphabet, non-canonical encoding or invalid UTF-8),\nwhich results in `CookieParseError` being thrown from the `parseCookie` function.\n\n##### Generic Decoders\n\n- **base64Decoder** - decodes base64 encoded string into UTF-8 string\n- **base64urlDecoder** - decodes base64url encoded string into UTF-8 string\n\n##### Cookie Name Decoders\n\n- **cookieNamePercentDecoder** - decodes percent-encoded cookie name, reverses `cookieNameStrictPercentEncoder` and `cookieNameLenientPercentEncoder`\n\n##### Cookie Value Decoders\n\nCookie value decoders preserve the enclosing DQUOTEs, the same way cookie value encoders do.\n\n- **cookieValuePercentDecoder** - reverses `cookieValueStrictPercentEncoder` and `cookieValueLenientPercentEncoder`\n- **cookieValueBase64Decoder** - reverses `cookieValueStrictBase64Encoder` and `cookieValueLenientBase64Encoder`\n- **cookieValueBase64urlDecoder** - reverses `cookieValueStrictBase64urlEncoder` and `cookieValueLenientBase64urlEncoder`\n- **cookieValueRotatingDecoder** - tries base64url, base64 and percent decoders in this order and returns result of the first one that succeeds; never throws\n\nEncoding of a cookie value is not part of the cookie string, and the encoders leave values that are already valid untouched.\nWhen the encoding is unknown, **cookieValueRotatingDecoder** can be used to detect it on a best-effort basis.\nResults of the decoders that are not canonically encoded, not valid UTF-8 or contain control characters are rejected,\nso plain values like `bar`, `en` or `admin` are kept as they are.\n\n```js\nimport { cookieValueRotatingDecoder } from '@swaggerexpert/cookie';\n\ncookieValueRotatingDecoder('aMOpbGxv'); // => 'héllo' (base64url)\ncookieValueRotatingDecoder('hello%20world'); // => 'hello world' (percent-encoding)\ncookieValueRotatingDecoder('en'); // => 'en' (plain value)\n```\n\n> NOTE: detection is inherently ambiguous: `Ow` is both a valid plain value and base64url encoded `;`,\n> and `cookieValueRotatingDecoder('Ow')` returns `;`. Prefer explicit decoders when the encoding is known.\n\nCustom order of decoders can be provided using **createCookieValueRotatingDecoder** function:\n\n```js\nimport {\n createCookieValueRotatingDecoder,\n cookieValuePercentDecoder,\n cookieValueBase64urlDecoder,\n} from '@swaggerexpert/cookie';\n\nconst decoder = createCookieValueRotatingDecoder([cookieValuePercentDecoder, cookieValueBase64urlDecoder]);\n\ndecoder('Ow'); // => 'Ow'\n```\n\n#### Validators\n\nThe `@swaggerexpert/cookie` library provides a suite of validators designed to ensure that cookie names and values\ncomply with the necessary standards during **serialization**. These validators are strict about adherence to the rules\nwhile offering flexibility with both strict and lenient validation modes. Validators focus on validating input and\nthrowing descriptive errors for invalid values.\n\n##### Cookie Name Validators\n\n**cookieNameStrictValidator**\n\nValidates cookie names based on the `cookie-name` rule defined in [RFC 6265](https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1).\n\n```js\nimport { cookieNameStrictValidator } from '@swaggerexpert/cookie';\n\ncookieNameStrictValidator('ValidName'); // passes\ncookieNameStrictValidator('InvalidName<'); // throws: Invalid cookie name\n```\n\n\n**cookieNameLenientValidator**\n\nValidates cookie names based on the `lenient-cookie-name` rules Allows a broader range of characters than the strict validator.\n\n```js\nimport { cookieNameLenientValidator } from '@swaggerexpert/cookie';\n\ncookieNameLenientValidator('ValidLenientName'); // passes\ncookieNameLenientValidator('\\tInvalidLenientName'); // throws: Invalid cookie name\n```\n\n##### Cookie Value Validators\n\n**cookieValueStrictValidator**\n\nValidates cookie values according to the `cookie-value` rules in [RFC 6265](https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1).\n\n```js\nimport { cookieValueStrictValidator } from '@swaggerexpert/cookie';\n\ncookieValueStrictValidator('\"validValue\"'); // passes\ncookieValueStrictValidator('invalid\\\\value'); // throws: Invalid cookie value\n```\n\n**cookieValueLenientValidator**\n\nValidates cookie values according to `lenient-cookie-value` rules. Accepts a broader range of characters,\nincluding some that are disallowed in strict mode.\n\n```js\nimport { cookieValueLenientValidator } from '@swaggerexpert/cookie';\n\ncookieValueLenientValidator('\"lenient;value\"'); // passes\ncookieValueLenientValidator('invalid value'); // throws: Invalid cookie value\n```\n\n#### Errors\n\n`@swaggerexpert/cookie` provides a structured error class hierarchy,\nenabling precise error handling.\n\n```js\nimport { CookieError, CookieParseError } from '@swaggerexpert/cookie';\n```\n\n**CookieError** is the base class for all errors. **CookieParseError** is thrown when parsing fails unexpectedly\nand includes additional context about the cookie string that failed to parse.\nPassing a non-string value to the `parseCookie` function throws a `TypeError`.\n\n```js\nimport { parseCookie, CookieParseError } from '@swaggerexpert/cookie';\n\ntry {\n parseCookie('foo=bar');\n} catch (error) {\n if (error instanceof CookieParseError) {\n console.log(error.cookieString); // the cookie string that failed to parse\n }\n}\n```\n\n#### Grammar\n\nNew grammar instance can be created in following way:\n\n```js\nimport { Grammar } from '@swaggerexpert/cookie';\n\nconst grammar = new Grammar();\n```\n\nTo obtain original ABNF (SABNF) grammar as a string:\n\n```js\nimport { Grammar } from '@swaggerexpert/cookie';\n\nconst grammar = new Grammar();\n\ngrammar.toString();\n// or\nString(grammar);\n```\n\n## More about RFC 6265\n\nThe cookie is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax\n\n```abnf\n; Lenient version of https://datatracker.ietf.org/doc/html/rfc6265#section-4.2.1\nlenient-cookie-string = lenient-cookie-entry *( \";\" OWS lenient-cookie-entry )\nlenient-cookie-entry = lenient-cookie-pair / lenient-cookie-pair-invalid\nlenient-cookie-pair = OWS lenient-cookie-name OWS \"=\" OWS lenient-cookie-value OWS\nlenient-cookie-pair-invalid = OWS 1*tchar OWS ; Allow for standalone entries like \"fizz\" to be ignored\nlenient-cookie-name = 1*( %x21-3A / %x3C / %x3E-7E ) ; Allow all printable US-ASCII except \"=\"\nlenient-cookie-value = lenient-quoted-value [ *lenient-cookie-octet ] / *lenient-cookie-octet\nlenient-quoted-value = DQUOTE *( lenient-quoted-char ) DQUOTE\nlenient-quoted-char = %x20-21 / %x23-7E ; Allow all printable US-ASCII except DQUOTE\nlenient-cookie-octet = %x21-2B / %x2D-3A / %x3C-7E\n ; Allow all printable characters except CTLs, semicolon and SP\n\n; Lenient version of https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1\n; following parsing algorithm of https://datatracker.ietf.org/doc/html/rfc6265#section-5.2\nlenient-set-cookie-string = lenient-set-cookie-pair *( \";\" lenient-cookie-av )\nlenient-set-cookie-pair = *WSP lenient-set-cookie-name *WSP \"=\" *WSP lenient-set-cookie-value *WSP\nlenient-set-cookie-name = lenient-name-char *( *WSP lenient-name-char ) ; leading and trailing WSP is not part of the name\nlenient-set-cookie-value = [ lenient-value-char *( *WSP lenient-value-char ) ] ; leading and trailing WSP is not part of the value\nlenient-cookie-av = *WSP lenient-cookie-av-name *WSP [ \"=\" *WSP lenient-cookie-av-value *WSP ]\nlenient-cookie-av-name = [ lenient-name-char *( *WSP lenient-name-char ) ]\nlenient-cookie-av-value = [ lenient-value-char *( *WSP lenient-value-char ) ]\n; CTLs (except HTAB) are not allowed, as they are not allowed in HTTP field values (https://www.rfc-editor.org/rfc/rfc9110#section-5.5)\nlenient-name-char = %x21-3A / %x3C / %x3E-7E / %x80-10FFFF ; any CHAR except CTLs, WSP, \";\" and \"=\"\nlenient-value-char = %x21-3A / %x3C-7E / %x80-10FFFF ; any CHAR except CTLs, WSP and \";\"\n\n; https://datatracker.ietf.org/doc/html/rfc6265#section-4.2.1\ncookie-string = cookie-pair *( \";\" SP cookie-pair )\n\n; https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1\n; https://www.rfc-editor.org/errata/eid5518\ncookie-pair = cookie-name \"=\" cookie-value\ncookie-name = token\ncookie-value = ( DQUOTE *cookie-octet DQUOTE ) / *cookie-octet\n ; https://www.rfc-editor.org/errata/eid8242\ncookie-octet = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E\n ; US-ASCII characters excluding CTLs,\n ; whitespace, DQUOTE, comma, semicolon,\n ; and backslash\n\n; https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1\nset-cookie-string = cookie-pair *( \";\" SP cookie-av )\ncookie-av = extension-av\n ; MODIFICATION: originally\n ; cookie-av = expires-av / max-age-av / domain-av /\n ; path-av / secure-av / httponly-av /\n ; extension-av\n ; All the alternatives are subsets of extension-av. Parsers processing alternatives\n ; left-to-right without backtracking would commit to a partial match of a specific\n ; alternative (e.g. \"Secure \" or \"Max-Age=60 \") and fail, instead of matching extension-av.\nexpires-av = \"Expires=\" sane-cookie-date\nsane-cookie-date = rfc1123-date\n ; defined in [RFC2616], Section 3.3.1\nmax-age-av = \"Max-Age=\" non-zero-digit *DIGIT\n ; In practice, both expires-av and max-age-av\n ; are limited to dates representable by the\n ; user agent.\nnon-zero-digit = %x31-39\n ; digits 1 through 9\ndomain-av = \"Domain=\" domain-value\ndomain-value = subdomain\n ; defined in [RFC1034], Section 3.5, as\n ; enhanced by [RFC1123], Section 2.1\npath-av = \"Path=\" path-value\npath-value = *av-octet\n ; https://www.rfc-editor.org/errata/eid3444\nsecure-av = \"Secure\"\nhttponly-av = \"HttpOnly\"\nextension-av = *av-octet\n ; https://www.rfc-editor.org/errata/eid3444\nav-octet = %x20-3A / %x3C-7E\n ; any CHAR except CTLs or \";\"\n\n; https://datatracker.ietf.org/doc/html/rfc1034#section-3.5\n; https://datatracker.ietf.org/doc/html/rfc1123#section-2.1\nsubdomain = label *( \".\" label )\nlabel = let-dig *( *\"-\" let-dig )\n ; MODIFICATION: originally\n ;
![\"Tidelift\"](\"https://raw.githubusercontent.com/swaggerexpert/cookie/main/assets/tidelift.webp\")
\n