projektuebersicht/node_modules/undici/docs/docs/api/Cookies.md

Cookies

Stability: 2 - Stable

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

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

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

Cookie

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

• name {string} The cookie name.
• value {string} The cookie value.
• expires {Date|number} The cookie expiry time, as a Date or a Unix timestamp in seconds. (optional)
• maxAge {number} The number of seconds until the cookie expires. (optional)
• domain {string} The hosts the cookie is sent to. (optional)
• path {string} The URL path that must exist for the cookie to be sent. (optional)
• secure {boolean} Whether the cookie is only sent over HTTPS. (optional)
• httpOnly {boolean} Whether the cookie is inaccessible to client-side JavaScript. (optional)
• sameSite {string} Controls whether the cookie is sent with cross-site requests. One of 'Strict', 'Lax', or 'None'. (optional)
• unparsed {string[]} Any attributes that were present in the Set-Cookie header but not recognized, each formatted as `name=value`. (optional)

getCookies(headers)

• headers {Headers} The Headers to read the Cookie header from.
• Returns: {Record<string, string>} A map of cookie names to values.

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

import { getCookies, Headers } from 'undici'

const headers = new Headers({
  cookie: 'get=cookies; and=attributes'
})

console.log(getCookies(headers)) // { get: 'cookies', and: 'attributes' }

deleteCookie(headers, name[, attributes])

• headers {Headers} The Headers to append the expiring cookie to.
• name {string} The name of the cookie to delete.
• attributes {Object} (optional)
  • path {string} The path the cookie was scoped to. Default: null.
  • domain {string} The domain the cookie was scoped to. Default: null.
• Returns: {undefined}

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

import { deleteCookie, Headers } from 'undici'

const headers = new Headers()
deleteCookie(headers, 'name')

console.log(headers.get('set-cookie')) // name=; Expires=Thu, 01 Jan 1970 00:00:00 GMT

getSetCookies(headers)

• headers {Headers} The Headers to read the Set-Cookie headers from.
• Returns: {Cookie[]} The parsed cookies, or an empty array when none are present.

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

import { getSetCookies, Headers } from 'undici'

const headers = new Headers({ 'set-cookie': 'undici=getSetCookies; Secure' })

console.log(getSetCookies(headers))
// [
//   {
//     name: 'undici',
//     value: 'getSetCookies',
//     secure: true
//   }
// ]

setCookie(headers, cookie)

• headers {Headers} The Headers to append the Set-Cookie header to.
• cookie {Cookie} The cookie to serialize. See Cookie.
• Returns: {undefined}

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

import { setCookie, Headers } from 'undici'

const headers = new Headers()
setCookie(headers, { name: 'undici', value: 'setCookie' })

console.log(headers.get('Set-Cookie')) // undici=setCookie

parseCookie(cookie)

• cookie {string} A Set-Cookie header value.
• Returns: {Cookie|null} The parsed cookie, or null if cookie is invalid.

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

import { parseCookie } from 'undici'

console.log(parseCookie('undici=getSetCookies; Secure; SameSite=Lax'))
// {
//   name: 'undici',
//   value: 'getSetCookies',
//   secure: true,
//   sameSite: 'Lax'
// }

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