Bun fournit des API natives pour travailler avec les cookies HTTP via Bun.Cookie et Bun.CookieMap. Ces API offrent des méthodes rapides et faciles à utiliser pour analyser, générer et manipuler les cookies dans les requêtes et réponses HTTP.

Classe CookieMap

Bun.CookieMap fournit une interface de type Map pour travailler avec des collections de cookies. Elle implémente l'interface Iterable, vous permettant de l'utiliser avec des boucles for...of et d'autres méthodes d'itération.

// Map de cookies vide
const cookies = new Bun.CookieMap();

// Depuis une chaîne de cookie
const cookies1 = new Bun.CookieMap("name=value; foo=bar");

// Depuis un objet
const cookies2 = new Bun.CookieMap({
  session: "abc123",
  theme: "dark",
});

// Depuis un tableau de paires nom/valeur
const cookies3 = new Bun.CookieMap([
  ["session", "abc123"],
  ["theme", "dark"],
]);

Dans les serveurs HTTP

Dans le serveur HTTP de Bun, la propriété cookies sur l'objet de requête (dans routes) est une instance de CookieMap :

const server = Bun.serve({
  routes: {
    "/" : req => {
      // Accéder aux cookies de la requête
      const cookies = req.cookies;

      // Obtenir un cookie spécifique
      const sessionCookie = cookies.get("session");
      if (sessionCookie != null) {
        console.log(sessionCookie);
      }

      // Vérifier si un cookie existe
      if (cookies.has("theme")) {
        // ...
      }

      // Définir un cookie, il sera automatiquement appliqué à la réponse
      cookies.set("visited", "true");

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

console.log("Serveur écoute sur : " + server.url);

Méthodes

get(name: string): string | null

Récupère un cookie par son nom. Retourne null si le cookie n'existe pas.

// Obtenir par nom
const cookie = cookies.get("session");

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

has(name: string): boolean

Vérifie si un cookie avec le nom donné existe.

// Vérifier si le cookie existe
if (cookies.has("session")) {
  // Le cookie existe
}

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

set(options: CookieInit): void

set(cookie: Cookie): void

Ajoute ou met à jour un cookie dans la map. Les cookies ont par défaut { path: "/", sameSite: "lax" }.

// Définir par nom et valeur
cookies.set("session", "abc123");

// Définir en utilisant un objet d'options
cookies.set({
  name: "theme",
  value: "dark",
  maxAge: 3600,
  secure: true,
});

// Définir en utilisant une instance Cookie
const cookie = new Bun.Cookie("visited", "true");
cookies.set(cookie);

delete(name: string): void

delete(options: CookieStoreDeleteOptions): void

Supprime un cookie de la map. Lorsqu'appliqué à une Response, cela ajoute un cookie avec une valeur de chaîne vide et une date d'expiration dans le passé. Un cookie ne sera supprimé avec succès dans le navigateur que si le domaine et le chemin sont les mêmes que lors de la création du cookie.

// Supprimer par nom en utilisant le domaine et le chemin par défaut.
cookies.delete("session");

// Supprimer avec les options domaine/chemin.
cookies.delete({
  name: "session",
  domain: "example.com",
  path: "/admin",
});

toJSON(): Record<string, string>

Convertit la map de cookies en un format sérialisable.

const json = cookies.toJSON();

toSetCookieHeaders(): string[]

Retourne un tableau de valeurs pour les en-têtes Set-Cookie qui peuvent être utilisés pour appliquer toutes les modifications de cookies.

Lors de l'utilisation de Bun.serve(), vous n'avez pas besoin d'appeler cette méthode explicitement. Toutes les modifications apportées à la map req.cookies sont automatiquement appliquées aux en-têtes de réponse. Cette méthode est principalement utile lors de l'utilisation d'autres implémentations de serveurs HTTP.

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(`Trouvé ${cookies.size} cookies`);
});

server.listen(3000, () => {
  console.log("Serveur en cours d'exécution sur http://localhost:3000/");
});

Itération

CookieMap fournit plusieurs méthodes pour l'itération :

// Itérer sur les entrées [nom, cookie]
for (const [name, value] of cookies) {
  console.log(`${name} : ${value}`);
}

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

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

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

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

Propriétés

size: number

Retourne le nombre de cookies dans la map.

console.log(cookies.size); // Nombre de cookies

Classe Cookie

Bun.Cookie représente un cookie HTTP avec son nom, sa valeur et ses attributs.

import { Cookie } from "bun";

// Créer un cookie basique
const cookie = new Bun.Cookie("name", "value");

// Créer un cookie avec des options
const secureSessionCookie = new Bun.Cookie("session", "abc123", {
  domain: "example.com",
  path: "/admin",
  expires: new Date(Date.now() + 86400000), // 1 jour
  httpOnly: true,
  secure: true,
  sameSite: "strict",
});

// Analyser depuis une chaîne de cookie
const parsedCookie = new Bun.Cookie("name=value; Path=/; HttpOnly");

// Créer depuis un objet d'options
const objCookie = new Bun.Cookie({
  name: "theme",
  value: "dark",
  maxAge: 3600,
  secure: true,
});

Constructeurs

// Constructeur basique avec nom/valeur
new Bun.Cookie(name: string, value: string);

// Constructeur avec nom, valeur et options
new Bun.Cookie(name: string, value: string, options: CookieInit);

// Constructeur depuis une chaîne de cookie
new Bun.Cookie(cookieString: string);

// Constructeur depuis un objet de cookie
new Bun.Cookie(options: CookieInit);

Propriétés

cookie.name; // string - Nom du cookie
cookie.value; // string - Valeur du cookie
cookie.domain; // string | null - Portée du domaine (null si non spécifié)
cookie.path; // string - Portée du chemin URL (par défaut "/")
cookie.expires; // number | undefined - Horodatage d'expiration (ms depuis epoch)
cookie.secure; // boolean - Nécessite HTTPS
cookie.sameSite; // "strict" | "lax" | "none" - Paramètre SameSite
cookie.partitioned; // boolean - Si le cookie est partitionné (CHIPS)
cookie.maxAge; // number | undefined - Âge maximum en secondes
cookie.httpOnly; // boolean - Accessible uniquement via HTTP (pas JavaScript)

Méthodes

isExpired(): boolean

Vérifie si le cookie a expiré.

// Cookie expiré (Date dans le passé)
const expiredCookie = new Bun.Cookie("name", "value", {
  expires: new Date(Date.now() - 1000),
});
console.log(expiredCookie.isExpired()); // true

// Cookie valide (Utilisation de maxAge au lieu de expires)
const validCookie = new Bun.Cookie("name", "value", {
  maxAge: 3600, // 1 heure en secondes
});
console.log(validCookie.isExpired()); // false

// Cookie de session (pas d'expiration)
const sessionCookie = new Bun.Cookie("name", "value");
console.log(sessionCookie.isExpired()); // false

serialize(): string

toString(): string

Retourne une représentation en chaîne du cookie adaptée à un en-tête Set-Cookie.

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

Convertit le cookie en un objet simple adapté à la sérialisation JSON.

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
// }

// Fonctionne avec JSON.stringify
const jsonString = JSON.stringify(cookie);

Méthodes statiques

Cookie.parse(cookieString: string): Cookie

Analyse une chaîne de cookie en une instance Cookie.

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éthode factory pour créer un cookie.

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

Types

interface CookieInit {
  name?: string;
  value?: string;
  domain?: string;
  /** Par défaut '/'. Pour permettre au navigateur de définir le chemin, utilisez une chaîne vide. */
  path?: string;
  expires?: number | Date | string;
  secure?: boolean;
  /** Par défaut `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]>;
}