Response Cookies

/**
 * Creates a ResponseCookies instance from response headers
 * @param responseHeaders - Headers object from an HTTP response
 */
constructor(responseHeaders: Headers);

import { ResponseCookies } from "@edge-runtime/cookies";

const response = new Response("Hello World");
const cookies = new ResponseCookies(response.headers);

// Or with existing Set-Cookie headers
const responseWithCookies = new Response("Hello", {
  headers: { "Set-Cookie": "session=abc123; HttpOnly; Secure" }
});
const existingCookies = new ResponseCookies(responseWithCookies.headers);

/**
 * Get a cookie by name or options (W3C CookieStore#get without Promise)
 * @param args - Cookie name as string or ResponseCookie options
 * @returns ResponseCookie object or undefined if not found
 */
get(...args: [key: string] | [options: ResponseCookie]): ResponseCookie | undefined;

// Get by name
const sessionCookie = cookies.get("session");
console.log(sessionCookie?.value); // "abc123"

// Get by options (matching by name)
const cookie = cookies.get({ name: "theme", value: "", path: "/" });
console.log(cookie?.httpOnly); // true or false

/**
 * Get all cookies or filter by name/options (W3C CookieStore#getAll without Promise)
 * @param args - Optional filter by name or ResponseCookie options
 * @returns Array of ResponseCookie objects
 */
getAll(...args: [key: string] | [options: ResponseCookie] | []): ResponseCookie[];

// Get all cookies
const allCookies = cookies.getAll();
console.log(allCookies.length); // Number of response cookies

// Filter by name
const sessionCookies = cookies.getAll("session");
console.log(sessionCookies); // Array of cookies named "session"

/**
 * Check if a cookie exists by name
 * @param name - Cookie name to check
 * @returns Boolean indicating existence
 */
has(name: string): boolean;

if (!cookies.has("csrf_token")) {
  cookies.set("csrf_token", generateCSRFToken());
}

/**
 * Set a cookie with attributes (W3C CookieStore#set without Promise)
 * @param args - Either key-value-options or full ResponseCookie object
 * @returns this for method chaining
 */
set(...args: [key: string, value: string, cookie?: Partial<ResponseCookie>] | [options: ResponseCookie]): this;

// Basic key-value
cookies.set("user", "john");

// With options
cookies.set("session", "abc123", {
  httpOnly: true,
  secure: true,
  maxAge: 86400, // 24 hours
  sameSite: "strict"
});

// Full ResponseCookie object
cookies.set({
  name: "preferences",
  value: JSON.stringify({ theme: "dark", lang: "en" }),
  path: "/",
  domain: ".example.com",
  expires: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000), // 30 days
  secure: true,
  httpOnly: false,
  sameSite: "lax"
});

// Method chaining
cookies
  .set("user", "john")
  .set("role", "admin", { httpOnly: true });

/**
 * Delete a cookie (W3C CookieStore#delete without Promise)
 * @param args - Cookie name or options (without value/expires)
 * @returns this for method chaining
 */
delete(...args: [key: string] | [options: Omit<ResponseCookie, 'value' | 'expires'>]): this;

// Delete by name
cookies.delete("session");

// Delete with specific path/domain
cookies.delete({
  name: "user",
  path: "/admin",
  domain: ".example.com"
});

/**
 * Format all cookies as a string for debugging
 * @returns Semicolon-separated cookie strings
 */
toString(): string;

console.log(cookies.toString());
// "session=abc123; HttpOnly; Secure; user=john; Path=/"

/**
 * Custom inspection method for debugging and logging
 * @returns Formatted string representation of response cookies
 */
[Symbol.for('edge-runtime.inspect.custom')](): string;

const cookies = new ResponseCookies(response.headers);
cookies.set("session", "abc123", { httpOnly: true });
cookies.set("theme", "dark", { path: "/" });

console.log(cookies[Symbol.for('edge-runtime.inspect.custom')]());
// "ResponseCookies {"session":{"name":"session","value":"abc123","httpOnly":true},"theme":{"name":"theme","value":"dark","path":"/"}}"

// Also works with Node.js util.inspect
import { inspect } from 'util';
console.log(inspect(cookies));
// Uses the custom inspection method automatically

interface ResponseCookie extends CookieListItem {
  /** Cookie name */
  name: string;
  /** Cookie value */
  value: string;
  /** Expiration date as Date object or milliseconds */
  expires?: number | Date;
  /** Cookie domain */
  domain?: string;
  /** Cookie path */
  path?: string;
  /** Secure flag - cookie only sent over HTTPS */
  secure?: boolean;
  /** SameSite attribute */
  sameSite?: 'strict' | 'lax' | 'none';
  /** Partitioned attribute for CHIPS */
  partitioned?: boolean;
  /** HttpOnly flag - cookie not accessible via JavaScript */
  httpOnly?: boolean;
  /** Max age in seconds */
  maxAge?: number;
  /** Priority hint for cookie eviction */
  priority?: 'low' | 'medium' | 'high';
}

cookies.set("comprehensive_cookie", "value123", {
  expires: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000), // 7 days
  domain: ".example.com",
  path: "/",
  secure: true,
  httpOnly: true,
  sameSite: "strict",
  partitioned: true,
  priority: "high"
});