Cookies

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.

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().

getCookies(headers): Record

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?): 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): Cookie

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): 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 | null

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.