Cookies

O módulo azion/cookies é a biblioteca da Azion Lib para cookies HTTP. As duas funções dele leem cookies do cabeçalho Cookie de um Request e definem um cookie em um Response pelo cabeçalho Set-Cookie. Elas não fazem chamadas de API, não precisam de token e retornam o resultado diretamente.

Instale o pacote:

npm install azion

O pacote azion recebe apenas correções de bugs, e a manutenção dele termina em dezembro de 2026.

As funções recebem os objetos padrão Request e Response. Elas rodam no Node.js e rodam dentro de uma function servida localmente com o azion dev. Os exemplos de getCookie e setCookie são módulos ES em TypeScript executados no Node.js, e eles importam tipos com import type. As duas funções também são propriedades do export padrão, cookies.

getCookie

Lê um cookie pelo nome, ou todos os cookies da requisição.

TypeScript

01function getCookie(req: Request, key?: string): string | undefined | Record<string, string>;

02function getCookie(req: Request, key: string, prefixOptions: CookiePrefix): string | undefined | Record<string, string>;

Parâmetro	Tipo	Obrigatório	Descrição
`req`	`Request`	Sim	A requisição que carrega o cabeçalho `Cookie`.
`key`	`string`	Não	O nome do cookie a ler. Sem ele, a função retorna todos os cookies. Obrigatório quando você passa `prefixOptions`.
`prefixOptions`	`CookiePrefix`	Não	O prefixo do nome do cookie. Com `host`, a função lê `__Host-<key>`; com `secure`, ela lê `__Secure-<key>`.

Retorna o valor do cookie como string quando você passa key, ou undefined quando a requisição não tem um cookie com esse nome. Sem key, retorna um Record<string, string> com todos os cookies, cada nome como a requisição o envia, com o prefixo incluído.

Este exemplo monta uma requisição com três cookies e lê um cookie, todos os cookies, um cookie __Host- e um cookie que não existe:

TypeScript

01import { getCookie } from 'azion/cookies';

03const request = new Request('https://example.com/', {

04 headers: { Cookie: 'my-cookie=cookie-value; theme=dark; __Host-session=abc123' },

05});

07console.log(getCookie(request, 'my-cookie')); // one cookie by name

08console.log(getCookie(request)); // every cookie as an object

09console.log(getCookie(request, 'session', 'host')); // reads __Host-session

10console.log(getCookie(request, 'missing')); // undefined

Saída:

Texto

01cookie-value

02{

03 'my-cookie': 'cookie-value',

04 theme: 'dark',

05 '__Host-session': 'abc123'

06}

07abc123

08undefined

setCookie

Define um cookie em uma resposta.

function setCookie(res: Response, key: string, value: string, options?: CookieOptions): Response;

Parâmetro	Tipo	Obrigatório	Descrição
`res`	`Response`	Sim	A resposta em que o cookie é definido.
`key`	`string`	Sim	O nome do cookie.
`value`	`string`	Sim	O valor do cookie.
`options`	`CookieOptions`	Não	Os atributos do cookie.

Retorna o Response com um cabeçalho Set-Cookie que contém o cookie e os atributos dele. Retorne essa resposta do seu handler, para que o cliente receba o cookie.

Com prefix: 'host', defina também path: '/'. Sem ele, setCookie lança um erro com a mensagem path option must be set to / when using host prefix.

Este exemplo define um cookie com cinco atributos, depois um cookie com o prefixo host, e imprime cada cabeçalho Set-Cookie:

TypeScript

01import { setCookie } from 'azion/cookies';

02import type { CookieOptions } from 'azion/cookies';

04const response = new Response('ok');

05const options: CookieOptions = { maxAge: 3600, path: '/', httpOnly: true, secure: true, sameSite: 'Lax' };

06const res: Response = setCookie(response, 'my-cookie', 'cookie-value', options);

07console.log(res.headers.get('Set-Cookie'));

09// the 'host' prefix requires path: '/'

10const res2 = setCookie(new Response('ok'), 'session', 'abc123', { prefix: 'host', secure: true, path: '/' });

11console.log(res2.headers.get('Set-Cookie'));

Saída:

Texto

01my-cookie=cookie-value; HttpOnly; Max-Age=3600; Path=/; SameSite=Lax; Secure

02__Host-session=abc123; Path=/; Secure

Ler e definir cookies em uma function

Esta function lê o cookie theme, usa light quando a requisição não tem esse cookie e define um cookie visited na resposta:

JavaScript

01import { getCookie, setCookie } from 'azion/cookies';

03export default {

04 async fetch(request) {

05 const theme = getCookie(request, 'theme') ?? 'light';

06 const response = new Response(`theme=${theme}; all=${JSON.stringify(getCookie(request))}\n`);

07 return setCookie(response, 'visited', 'true', { maxAge: 3600, path: '/', httpOnly: true });

08 },

09};

Servida localmente com azion dev, uma requisição com cabeçalho Cookie e uma requisição sem ele retornam:

Texto

01$ curl -H 'Cookie: theme=dark; lang=pt' http://localhost:3333/

02HTTP/1.1 200 OK

03content-type: text/plain;charset=UTF-8

04set-cookie: visited=true; HttpOnly; Max-Age=3600; Path=/

06theme=dark; all={"theme":"dark","lang":"pt"}

08$ curl http://localhost:3333/

09HTTP/1.1 200 OK

10content-type: text/plain;charset=UTF-8

11set-cookie: visited=true; HttpOnly; Max-Age=3600; Path=/

13theme=light; all={}

Tipos

O módulo exporta estes tipos. Importe-os com import type.

CookieOptions

Os atributos que setCookie grava no cookie.

Propriedade	Tipo	Obrigatório	Descrição
`domain`	`string`	Não	O domínio para o qual o cookie é válido.
`expires`	`Date`	Não	A data de expiração do cookie.
`httpOnly`	`boolean`	Não	Com `true`, adiciona o atributo `HttpOnly`, que deixa o cookie fora do alcance do JavaScript no navegador por `document.cookie`.
`maxAge`	`number`	Não	A idade máxima do cookie, em segundos. Gravado como `Max-Age`.
`path`	`string`	Não	O caminho para o qual o cliente envia o cookie. Deve ser `/` com `prefix: 'host'`.
`sameSite`	`'Lax' \| 'None' \| 'Strict'`	Não	Como o cliente envia o cookie com requisições entre sites.
`secure`	`boolean`	Não	Com `true`, adiciona o atributo `Secure`, para que o cliente envie o cookie apenas por HTTPS.
`prefix`	`CookiePrefix`	Não	O prefixo do nome. Com `host`, o nome do cookie começa com `__Host-`.
`partitioned`	`boolean`	Não	Com `true`, adiciona o atributo `Partitioned`.

CookiePrefix

O prefixo de nome que getCookie lê e setCookie grava.

type CookiePrefix = 'host' | 'secure';

Recursos relacionados

Azion Lib

As bibliotecas que a Azion Lib oferece e o pacote que carrega cada uma.

Request

O objeto de requisição do qual getCookie lê o cabeçalho Cookie.

Response

O objeto de resposta ao qual setCookie adiciona o cabeçalho Set-Cookie.

Azion CLI dev

Sirva uma function localmente e teste os cookies que ela lê e define.