O Bun fornece APIs nativas para trabalhar com cookies HTTP através de Bun.Cookie e Bun.CookieMap. Estas APIs oferecem métodos rápidos e fáceis de usar para analisar, gerar e manipular cookies em requisições e respostas HTTP.

Classe CookieMap

Bun.CookieMap fornece uma interface semelhante a Map para trabalhar com coleções de cookies. Implementa a interface Iterable, permitindo usá-la com loops for...of e outros métodos de iteração.

cookies.ts

// Mapa de cookies vazio
const cookies = new Bun.CookieMap();

// De uma string de cookie
const cookies1 = new Bun.CookieMap("name=value; foo=bar");

// De um objeto
const cookies2 = new Bun.CookieMap({
  session: "abc123",
  theme: "dark",
});

// De um array de pares nome/valor
const cookies3 = new Bun.CookieMap([
  ["session", "abc123"],
  ["theme", "dark"],
]);

Em servidores HTTP

No servidor HTTP do Bun, a propriedade cookies no objeto de requisição (em routes) é uma instância de CookieMap:

server.ts

const server = Bun.serve({
  routes: {
    "/": req => {
      // Acessa cookies da requisição
      const cookies = req.cookies;

      // Obtém um cookie específico
      const sessionCookie = cookies.get("session");
      if (sessionCookie != null) {
        console.log(sessionCookie);
      }

      // Verifica se um cookie existe
      if (cookies.has("theme")) {
        // ...
      }

      // Define um cookie, será aplicado automaticamente à resposta
      cookies.set("visited", "true");

      return new Response("Hello");
    },
  },
});

console.log("Server listening at: " + server.url);

Métodos

get(name: string): string | null

Recupera um cookie por nome. Retorna null se o cookie não existir.

get-cookie.ts

// Obtém por nome
const cookie = cookies.get("session");

if (cookie != null) {
  console.log(cookie);
}

has(name: string): boolean

Verifica se um cookie com o nome dado existe.

has-cookie.ts

// Verifica se cookie existe
if (cookies.has("session")) {
  // Cookie existe
}

set(name: string, value: string): void

set(options: CookieInit): void

set(cookie: Cookie): void

Adiciona ou atualiza um cookie no mapa. Cookies padrão para { path: "/", sameSite: "lax" }.

set-cookie.ts

// Define por nome e valor
cookies.set("session", "abc123");

// Define usando objeto de opções
cookies.set({
  name: "theme",
  value: "dark",
  maxAge: 3600,
  secure: true,
});

// Define usando instância Cookie
const cookie = new Bun.Cookie("visited", "true");
cookies.set(cookie);

delete(name: string): void

delete(options: CookieStoreDeleteOptions): void

Remove um cookie do mapa. Quando aplicado a uma Response, isso adiciona um cookie com valor de string vazia e uma data de expiração no passado. Um cookie só será excluído com sucesso no navegador se o domínio e caminho forem os mesmos de quando o cookie foi criado.

delete-cookie.ts

// Exclui por nome usando domínio e caminho padrão.
cookies.delete("session");

// Exclui com opções de domínio/caminho.
cookies.delete({
  name: "session",
  domain: "example.com",
  path: "/admin",
});

toJSON(): Record<string, string>

Converte o mapa de cookies para um formato serializável.

cookie-to-json.ts

const json = cookies.toJSON();

toSetCookieHeaders(): string[]

Retorna um array de valores para cabeçalhos Set-Cookie que podem ser usados para aplicar todas as alterações de cookies.

Ao usar Bun.serve(), você não precisa chamar este método explicitamente. Quaisquer alterações feitas no mapa req.cookies são automaticamente aplicadas aos cabeçalhos de resposta. Este método é principalmente útil quando trabalhando com outras implementações de servidor HTTP.

node-server.js

import { createServer } from "node:http";
import { CookieMap } from "bun";

const server = createServer((req, res) => {
  const cookieHeader = req.headers.cookie || "";
  const cookies = new CookieMap(cookieHeader);

  cookies.set("view-count", Number(cookies.get("view-count") || "0") + 1);
  cookies.delete("session");

  res.writeHead(200, {
    "Content-Type": "text/plain",
    "Set-Cookie": cookies.toSetCookieHeaders(),
  });
  res.end(`Found ${cookies.size} cookies`);
});

server.listen(3000, () => {
  console.log("Server running at http://localhost:3000/");
});

Iteração

CookieMap fornece vários métodos para iteração:

iterate-cookies.ts

// Itera sobre entradas [nome, cookie]
for (const [name, value] of cookies) {
  console.log(`${name}: ${value}`);
}

// Usando entries()
for (const [name, value] of cookies.entries()) {
  console.log(`${name}: ${value}`);
}

// Usando keys()
for (const name of cookies.keys()) {
  console.log(name);
}

// Usando values()
for (const value of cookies.values()) {
  console.log(value);
}

// Usando forEach
cookies.forEach((value, name) => {
  console.log(`${name}: ${value}`);
});

Propriedades

size: number

Retorna o número de cookies no mapa.

cookie-size.ts

console.log(cookies.size); // Número de cookies

Classe Cookie

Bun.Cookie representa um cookie HTTP com seu nome, valor e atributos.

cookie-class.ts

import { Cookie } from "bun";

// Cria um cookie básico
const cookie = new Bun.Cookie("name", "value");

// Cria um cookie com opções
const secureSessionCookie = new Bun.Cookie("session", "abc123", {
  domain: "example.com",
  path: "/admin",
  expires: new Date(Date.now() + 86400000), // 1 dia
  httpOnly: true,
  secure: true,
  sameSite: "strict",
});

// Analisa de uma string de cookie
const parsedCookie = new Bun.Cookie("name=value; Path=/; HttpOnly");

// Cria de um objeto de opções
const objCookie = new Bun.Cookie({
  name: "theme",
  value: "dark",
  maxAge: 3600,
  secure: true,
});

Construtores

constructors.ts

// Construtor básico com nome/valor
new Bun.Cookie(name: string, value: string);

// Construtor com nome, valor e opções
new Bun.Cookie(name: string, value: string, options: CookieInit);

// Construtor de string de cookie
new Bun.Cookie(cookieString: string);

// Construtor de objeto de cookie
new Bun.Cookie(options: CookieInit);

Propriedades

cookie-properties.ts

cookie.name; // string - Nome do cookie
cookie.value; // string - Valor do cookie
cookie.domain; // string | null - Escopo de domínio (null se não especificado)
cookie.path; // string - Escopo de caminho URL (padrão "/")
cookie.expires; // number | undefined - Timestamp de expiração (ms desde epoch)
cookie.secure; // boolean - Requer HTTPS
cookie.sameSite; // "strict" | "lax" | "none" - Configuração SameSite
cookie.partitioned; // boolean - Se o cookie está particionado (CHIPS)
cookie.maxAge; // number | undefined - Idade máxima em segundos
cookie.httpOnly; // boolean - Acessível apenas via HTTP (não JavaScript)

Métodos

isExpired(): boolean

Verifica se o cookie expirou.

is-expired.ts

// Cookie expirado (Data no passado)
const expiredCookie = new Bun.Cookie("name", "value", {
  expires: new Date(Date.now() - 1000),
});
console.log(expiredCookie.isExpired()); // true

// Cookie válido (Usando maxAge em vez de expires)
const validCookie = new Bun.Cookie("name", "value", {
  maxAge: 3600, // 1 hora em segundos
});
console.log(validCookie.isExpired()); // false

// Cookie de sessão (sem expiração)
const sessionCookie = new Bun.Cookie("name", "value");
console.log(sessionCookie.isExpired()); // false

serialize(): string

toString(): string

Retorna uma representação em string do cookie adequada para um cabeçalho Set-Cookie.

serialize-cookie.ts

const cookie = new Bun.Cookie("session", "abc123", {
  domain: "example.com",
  path: "/admin",
  expires: new Date(Date.now() + 86400000),
  secure: true,
  httpOnly: true,
  sameSite: "strict",
});

console.log(cookie.serialize());
// => "session=abc123; Domain=example.com; Path=/admin; Expires=Sun, 19 Mar 2025 15:03:26 GMT; Secure; HttpOnly; SameSite=strict"
console.log(cookie.toString());
// => "session=abc123; Domain=example.com; Path=/admin; Expires=Sun, 19 Mar 2025 15:03:26 GMT; Secure; HttpOnly; SameSite=strict"

toJSON(): CookieInit

Converte o cookie para um objeto simples adequado para serialização JSON.

cookie-json.ts

const cookie = new Bun.Cookie("session", "abc123", {
  secure: true,
  httpOnly: true,
});

const json = cookie.toJSON();
// => {
//   name: "session",
//   value: "abc123",
//   path: "/",
//   secure: true,
//   httpOnly: true,
//   sameSite: "lax",
//   partitioned: false
// }

// Funciona com JSON.stringify
const jsonString = JSON.stringify(cookie);

Métodos estáticos

Cookie.parse(cookieString: string): Cookie

Analisa uma string de cookie em uma instância Cookie.

parse-cookie.ts

const cookie = Bun.Cookie.parse("name=value; Path=/; Secure; SameSite=Lax");

console.log(cookie.name); // "name"
console.log(cookie.value); // "value"
console.log(cookie.path); // "/"
console.log(cookie.secure); // true
console.log(cookie.sameSite); // "lax"

Cookie.from(name: string, value: string, options?: CookieInit): Cookie

Método factory para criar um cookie.

cookie-from.ts

const cookie = Bun.Cookie.from("session", "abc123", {
  httpOnly: true,
  secure: true,
  maxAge: 3600,
});

Tipos

types.ts

interface CookieInit {
  name?: string;
  value?: string;
  domain?: string;
  /** Padrão '/'. Para permitir que o navegador defina o caminho, use string vazia. */
  path?: string;
  expires?: number | Date | string;
  secure?: boolean;
  /** Padrão `lax`. */
  sameSite?: CookieSameSite;
  httpOnly?: boolean;
  partitioned?: boolean;
  maxAge?: number;
}

interface CookieStoreDeleteOptions {
  name: string;
  domain?: string | null;
  path?: string;
}

interface CookieStoreGetOptions {
  name?: string;
  url?: string;
}

type CookieSameSite = "strict" | "lax" | "none";

class Cookie {
  constructor(name: string, value: string, options?: CookieInit);
  constructor(cookieString: string);
  constructor(cookieObject?: CookieInit);

  readonly name: string;
  value: string;
  domain?: string;
  path: string;
  expires?: Date;
  secure: boolean;
  sameSite: CookieSameSite;
  partitioned: boolean;
  maxAge?: number;
  httpOnly: boolean;

  isExpired(): boolean;

  serialize(): string;
  toString(): string;
  toJSON(): CookieInit;

  static parse(cookieString: string): Cookie;
  static from(name: string, value: string, options?: CookieInit): Cookie;
}

class CookieMap implements Iterable<[string, string]> {
  constructor(init?: string[][] | Record<string, string> | string);

  get(name: string): string | null;

  toSetCookieHeaders(): string[];

  has(name: string): boolean;
  set(name: string, value: string, options?: CookieInit): void;
  set(options: CookieInit): void;
  delete(name: string): void;
  delete(options: CookieStoreDeleteOptions): void;
  delete(name: string, options: Omit<CookieStoreDeleteOptions, "name">): void;
  toJSON(): Record<string, string>;

  readonly size: number;

  entries(): IterableIterator<[string, string]>;
  keys(): IterableIterator<string>;
  values(): IterableIterator<string>;
  forEach(callback: (value: string, key: string, map: CookieMap) => void): void;
  [Symbol.iterator](): IterableIterator<[string, string]>;
}