\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 - [Serializing cookie](#serializing-cookie)\n - [Encoders](#encoders)\n - [Cookie Name encoders](#cookie-name-encoders)\n - [Cookie Value encoders](#cookie-value-encoders)\n - [Validators](#validators)\n - [Cookie Name validators](#cookie-name-validators)\n - [Cookie Value validators](#cookie-value-validators)\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### 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** returned by the parser has the following shape:\n\n```\n{\n result: {\n success: true,\n state: 101,\n stateName: 'MATCH',\n length: 7,\n matched: 7,\n maxMatched: 7,\n maxTreeDepth: 9,\n nodeHits: 71\n },\n ast: fnast {\n callbacks: [\n 'cookie-string': [Function: cookieString],\n 'cookie-pair': [Function: cookiePair],\n 'cookie-name': [Function: cookieName],\n 'cookie-value': [Function: cookieValue]\n ],\n init: [Function (anonymous)],\n ruleDefined: [Function (anonymous)],\n udtDefined: [Function (anonymous)],\n down: [Function (anonymous)],\n up: [Function (anonymous)],\n translate: [Function (anonymous)],\n setLength: [Function (anonymous)],\n getLength: [Function (anonymous)],\n toXml: [Function (anonymous)]\n }\n}\n```\n\n###### Interpreting AST as list of entries\n\n```js\nimport { parseCookie } from '@swaggerexpert/cookie';\n\nconst parseResult = parse('foo=bar');\nconst parts = [];\n\nparseResult.ast.translate(parts);\n```\n\nAfter running the above code, **parts** 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###### Interpreting AST as XML\n\n```js\nimport { parseCookie } from '@swaggerexpert/cookie';\n\nconst parseResult = parseCookie('foo=bar');\nconst xml = parseResult.ast.toXml();\n```\n\nAfter running the above code, **xml** variable has the following content:\n\n```xml\n\n\n \n foo=bar\n \n foo=bar\n \n foo=bar\n \n foo\n \n \n bar\n \n \n \n\n```\n\n> NOTE: AST can also be traversed in classical way using [depth first traversal](https://www.tutorialspoint.com/data_structures_algorithms/depth_first_traversal.htm). For more information about this option please refer to [apg-js](https://github.com/ldthomas/apg-js) and [apg-js-examples](https://github.com/ldthomas/apg-js-examples).\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#### 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#### 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#### 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; 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-2.2\nOWS = *( [ CRLF ] WSP ) ; \"optional\" whitespace\n\n; https://datatracker.ietf.org/doc/html/rfc9110#section-5.6.2\ntoken = 1*(tchar)\ntchar = \"!\" / \"#\" / \"$\" / \"%\" / \"&\" / \"'\" / \"*\"\n / \"+\" / \"-\" / \".\" / \"^\" / \"_\" / \"`\" / \"|\" / \"~\"\n / DIGIT / ALPHA\n ; any VCHAR, except delimiters\n\n; https://datatracker.ietf.org/doc/html/rfc2616#section-2.2\nCHAR = %x01-7F ; any US-ASCII character (octets 0 - 127)\nCTL = %x00-1F / %x7F ; any US-ASCII control character\nseparators = \"(\" / \")\" / \"<\" / \">\" / \"@\" / \",\" / \";\" / \":\" / \"\\\" / %x22 / \"/\" / \"[\" / \"]\" / \"?\" / \"=\" / \"{\" / \"}\" / SP / HT\nSP = %x20 ; US-ASCII SP, space (32)\nHT = %x09 ; US-ASCII HT, horizontal-tab (9)\n\n; https://datatracker.ietf.org/doc/html/rfc5234#appendix-B.1\nALPHA = %x41-5A / %x61-7A ; A-Z / a-z\nDIGIT = %x30-39 ; 0-9\nDQUOTE = %x22 ; \" (Double Quote)\nWSP = SP / HTAB ; white space\nHTAB = %x09 ; horizontal tab\nCRLF = CR LF ; Internet standard newline\nCR = %x0D ; carriage return\nLF = %x0A ; linefeed\n```\n\n## License\n\n`@swaggerexpert/cookie` is licensed under [Apache 2.0 license](https://github.com/swaggerexpert/cookie/blob/main/LICENSE).\n`@swaggerexpert/cookie` comes with an explicit [NOTICE](https://github.com/swaggerexpert/cookie/blob/main/NOTICE) file\ncontaining additional legal notices and information.","users":{}}
![\"Tidelift\"](\"https://cdn2.hubspot.net/hubfs/4008838/website/logos/logos_for_download/Tidelift_primary-shorthand-logo.png\"){kind=logo}
\n