# 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: ```bash 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](/pt-br/documentacao/devtools/runtime/api-reference/request/) e [Response](/pt-br/documentacao/devtools/runtime/api-reference/response/). Elas rodam no Node.js e rodam dentro de uma function servida localmente com o [azion dev](/pt-br/documentacao/devtools/cli/dev-comando/). 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 function getCookie(req: Request, key?: string): string | undefined | Record; function getCookie(req: Request, key: string, prefixOptions: CookiePrefix): string | undefined | Record; ``` | 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`](#cookieprefix) | Não | O prefixo do nome do cookie. Com `host`, a função lê `__Host-`; com `secure`, ela lê `__Secure-`. | 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` 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 import { getCookie } from 'azion/cookies'; const request = new Request('https://example.com/', { headers: { Cookie: 'my-cookie=cookie-value; theme=dark; __Host-session=abc123' }, }); console.log(getCookie(request, 'my-cookie')); // one cookie by name console.log(getCookie(request)); // every cookie as an object console.log(getCookie(request, 'session', 'host')); // reads __Host-session console.log(getCookie(request, 'missing')); // undefined ``` Saída: ```text cookie-value { 'my-cookie': 'cookie-value', theme: 'dark', '__Host-session': 'abc123' } abc123 undefined ``` --- ## setCookie Define um cookie em uma resposta. ```typescript 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`](#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 import { setCookie } from 'azion/cookies'; import type { CookieOptions } from 'azion/cookies'; const response = new Response('ok'); const options: CookieOptions = { maxAge: 3600, path: '/', httpOnly: true, secure: true, sameSite: 'Lax' }; const res: Response = setCookie(response, 'my-cookie', 'cookie-value', options); console.log(res.headers.get('Set-Cookie')); // the 'host' prefix requires path: '/' const res2 = setCookie(new Response('ok'), 'session', 'abc123', { prefix: 'host', secure: true, path: '/' }); console.log(res2.headers.get('Set-Cookie')); ``` Saída: ```text my-cookie=cookie-value; HttpOnly; Max-Age=3600; Path=/; SameSite=Lax; Secure __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 import { getCookie, setCookie } from 'azion/cookies'; export default { async fetch(request) { const theme = getCookie(request, 'theme') ?? 'light'; const response = new Response(`theme=${theme}; all=${JSON.stringify(getCookie(request))}\n`); return setCookie(response, 'visited', 'true', { maxAge: 3600, path: '/', httpOnly: true }); }, }; ``` Servida localmente com `azion dev`, uma requisição com cabeçalho `Cookie` e uma requisição sem ele retornam: ```text $ curl -H 'Cookie: theme=dark; lang=pt' http://localhost:3333/ HTTP/1.1 200 OK content-type: text/plain;charset=UTF-8 set-cookie: visited=true; HttpOnly; Max-Age=3600; Path=/ theme=dark; all={"theme":"dark","lang":"pt"} $ curl http://localhost:3333/ HTTP/1.1 200 OK content-type: text/plain;charset=UTF-8 set-cookie: visited=true; HttpOnly; Max-Age=3600; Path=/ theme=light; all={} ``` --- ## Tipos O módulo exporta estes tipos. Importe-os com `import type`. ### CookieOptions Os atributos que [setCookie](#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`](#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](#getcookie) lê e [setCookie](#setcookie) grava. ```typescript type CookiePrefix = 'host' | 'secure'; ``` --- ## Recursos relacionados - [Azion Lib](/pt-br/documentacao/devtools/azion-lib.md): As bibliotecas que a Azion Lib oferece e o pacote que carrega cada uma. - [Request](/pt-br/documentacao/devtools/runtime/api-reference/request.md): O objeto de requisição do qual getCookie lê o cabeçalho Cookie. - [Response](/pt-br/documentacao/devtools/runtime/api-reference/response.md): O objeto de resposta ao qual setCookie adiciona o cabeçalho Set-Cookie. - [Azion CLI dev](/pt-br/documentacao/devtools/cli/dev-comando.md): Sirva uma function localmente e teste os cookies que ela lê e define.