{ "type": "module", "source": "doc/api/api-cookies.md", "modules": [ { "textRaw": "Cookies", "name": "cookies", "introduced_in": "v5.15.0", "type": "module", "stability": 2, "stabilityText": "Stable", "desc": "

A set of helpers for reading and writing HTTP cookies on a Headers\ninstance, following the RFC 6265bis cookie parsing and serialization\nalgorithm. They operate on the Cookie request header and the Set-Cookie\nresponse header.

\n
import { getCookies, setCookie, deleteCookie, getSetCookies, parseCookie } from 'undici'\n
\n

These functions do not manage a cookie jar or perform any network activity; they\nonly read from and mutate the supplied Headers object.

", "modules": [ { "textRaw": "`Cookie`", "name": "`cookie`", "type": "module", "desc": "

The Cookie object describes a single cookie and its attributes. It is the\nreturn shape of parseCookie() and getSetCookies(), and the input\nshape accepted by setCookie().

\n", "displayName": "`Cookie`" } ], "methods": [ { "textRaw": "`getCookies(headers)`", "name": "getCookies", "type": "method", "meta": { "added": [ "v5.15.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`headers` {Headers} The `Headers` to read the `Cookie` header from.", "name": "headers", "type": "Headers", "desc": "The `Headers` to read the `Cookie` header from." } ], "return": { "textRaw": "Returns: {Record}<{string}, {string}> A map of cookie names to values.", "name": "return", "type": "Record", "desc": "<{string}, {string}> A map of cookie names to values." } } ], "desc": "

Parses the Cookie header of headers and returns its name/value pairs as a\nplain object. An empty object is returned when no Cookie header is present.

\n
import { getCookies, Headers } from 'undici'\n\nconst headers = new Headers({\n  cookie: 'get=cookies; and=attributes'\n})\n\nconsole.log(getCookies(headers)) // { get: 'cookies', and: 'attributes' }\n
" }, { "textRaw": "`deleteCookie(headers, name[, attributes])`", "name": "deleteCookie", "type": "method", "meta": { "added": [ "v5.15.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`headers` {Headers} The `Headers` to append the expiring cookie to.", "name": "headers", "type": "Headers", "desc": "The `Headers` to append the expiring cookie to." }, { "textRaw": "`name` {string} The name of the cookie to delete.", "name": "name", "type": "string", "desc": "The name of the cookie to delete." }, { "textRaw": "`attributes` {Object} (optional)", "name": "attributes", "type": "Object", "desc": "(optional)", "options": [ { "textRaw": "`path` {string} The path the cookie was scoped to. **Default:** `null`.", "name": "path", "type": "string", "default": "`null`", "desc": "The path the cookie was scoped to." }, { "textRaw": "`domain` {string} The domain the cookie was scoped to. **Default:** `null`.", "name": "domain", "type": "string", "default": "`null`", "desc": "The domain the cookie was scoped to." } ], "optional": true } ], "return": { "textRaw": "Returns: {undefined}", "name": "return", "type": "undefined" } } ], "desc": "

Appends a Set-Cookie header to headers that expires the named cookie by\nsetting its expiry time to the Unix epoch, causing a client to delete it on\nreceipt. The optional path and domain must match those of the cookie being\nremoved.

\n
import { deleteCookie, Headers } from 'undici'\n\nconst headers = new Headers()\ndeleteCookie(headers, 'name')\n\nconsole.log(headers.get('set-cookie')) // name=; Expires=Thu, 01 Jan 1970 00:00:00 GMT\n
" }, { "textRaw": "`getSetCookies(headers)`", "name": "getSetCookies", "type": "method", "meta": { "added": [ "v5.15.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`headers` {Headers} The `Headers` to read the `Set-Cookie` headers from.", "name": "headers", "type": "Headers", "desc": "The `Headers` to read the `Set-Cookie` headers from." } ], "return": { "textRaw": "Returns: {Cookie}[] The parsed cookies, or an empty array when none are present.", "name": "return", "type": "Cookie", "desc": "[] The parsed cookies, or an empty array when none are present." } } ], "desc": "

Parses every Set-Cookie header of headers and returns the resulting\nCookie objects. A header that fails to parse yields a null entry at its\nposition in the returned array.

\n
import { getSetCookies, Headers } from 'undici'\n\nconst headers = new Headers({ 'set-cookie': 'undici=getSetCookies; Secure' })\n\nconsole.log(getSetCookies(headers))\n// [\n//   {\n//     name: 'undici',\n//     value: 'getSetCookies',\n//     secure: true\n//   }\n// ]\n
" }, { "textRaw": "`setCookie(headers, cookie)`", "name": "setCookie", "type": "method", "meta": { "added": [ "v5.15.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`headers` {Headers} The `Headers` to append the `Set-Cookie` header to.", "name": "headers", "type": "Headers", "desc": "The `Headers` to append the `Set-Cookie` header to." }, { "textRaw": "`cookie` {Cookie} The cookie to serialize. See `Cookie`.", "name": "cookie", "type": "Cookie", "desc": "The cookie to serialize. See `Cookie`." } ], "return": { "textRaw": "Returns: {undefined}", "name": "return", "type": "undefined" } } ], "desc": "

Serializes cookie and appends it to the Set-Cookie header of headers. When\nthe cookie name is empty, serialization yields no value and no header is\nappended.

\n
import { setCookie, Headers } from 'undici'\n\nconst headers = new Headers()\nsetCookie(headers, { name: 'undici', value: 'setCookie' })\n\nconsole.log(headers.get('Set-Cookie')) // undici=setCookie\n
" }, { "textRaw": "`parseCookie(cookie)`", "name": "parseCookie", "type": "method", "meta": { "added": [ "v7.0.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`cookie` {string} A `Set-Cookie` header value.", "name": "cookie", "type": "string", "desc": "A `Set-Cookie` header value." } ], "return": { "textRaw": "Returns: {Cookie|null} The parsed cookie, or `null` if `cookie` is invalid.", "name": "return", "type": "Cookie|null", "desc": "The parsed cookie, or `null` if `cookie` is invalid." } } ], "desc": "

Parses a single Set-Cookie header value into a Cookie object. null is\nreturned when the value contains control characters or otherwise cannot be\nparsed.

\n
import { parseCookie } from 'undici'\n\nconsole.log(parseCookie('undici=getSetCookies; Secure; SameSite=Lax'))\n// {\n//   name: 'undici',\n//   value: 'getSetCookies',\n//   secure: true,\n//   sameSite: 'Lax'\n// }\n
\n

The cookie value is returned exactly as it appears in the header; percent-encoded\nsequences such as %20 or %0D%0A are not decoded. The sameSite attribute is\nonly set when the value is a case-insensitive match for Strict, Lax, or\nNone.

" } ] } ] }