Request Cookies

/**
 * Creates a RequestCookies instance from request headers
 * @param requestHeaders - Headers object from an HTTP request
 */
constructor(requestHeaders: Headers);

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

const request = new Request("https://example.com", {
  headers: { "Cookie": "session=abc123; theme=dark; lang=en" }
});

const cookies = new RequestCookies(request.headers);

/**
 * The amount of cookies received from the client
 */
get size(): number;

const cookies = new RequestCookies(request.headers);
console.log(`Received ${cookies.size} cookies`); // "Received 3 cookies"

/**
 * Get a cookie by name
 * @param name - Cookie name as string, or RequestCookie object
 * @returns RequestCookie object or undefined if not found
 */
get(...args: [name: string] | [RequestCookie]): RequestCookie | undefined;

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

// Get by RequestCookie object
const cookie = cookies.get({ name: "theme", value: "" });
console.log(cookie?.value); // "dark"

/**
 * Get all cookies or filter by name
 * @param args - Optional name filter as string or RequestCookie object
 * @returns Array of RequestCookie objects
 */
getAll(...args: [name: string] | [RequestCookie] | []): RequestCookie[];

// Get all cookies
const allCookies = cookies.getAll();
console.log(allCookies); // [{ name: "session", value: "abc123" }, ...]

// Filter by name
const sessionCookies = cookies.getAll("session");
console.log(sessionCookies); // [{ name: "session", value: "abc123" }]

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

if (cookies.has("session")) {
  console.log("User is logged in");
}

/**
 * Set or update a cookie in the request
 * @param args - Either key-value pair or RequestCookie object
 * @returns this for method chaining
 */
set(...args: [key: string, value: string] | [options: RequestCookie]): this;

// Set by key-value
cookies.set("newCookie", "newValue");

// Set by RequestCookie object
cookies.set({ name: "preference", value: "compact" });

// Method chaining
cookies
  .set("user", "john")
  .set("role", "admin");

/**
 * Delete cookies by name from the request
 * @param names - Single name or array of names to delete
 * @returns Boolean or array of booleans indicating success
 */
delete(names: string | string[]): boolean | boolean[];

// Delete single cookie
const deleted = cookies.delete("session");
console.log(deleted); // true if existed, false otherwise

// Delete multiple cookies
const results = cookies.delete(["theme", "lang", "nonexistent"]);
console.log(results); // [true, true, false]

/**
 * Delete all cookies from the request
 * @returns this for method chaining
 */
clear(): this;

cookies.clear();
console.log(cookies.size); // 0

/**
 * Format cookies as a string for logging/debugging
 * @returns URL-encoded cookie string
 */
toString(): string;

console.log(cookies.toString());
// "session=abc123; theme=dark; lang=en"

/**
 * Makes the class iterable over cookie entries
 * @returns Iterator yielding [name, RequestCookie] pairs
 */
[Symbol.iterator](): Iterator<[string, RequestCookie]>;

for (const [name, cookie] of cookies) {
  console.log(`${name}: ${cookie.value}`);
}
// Output:
// session: abc123
// theme: dark
// lang: en

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

const cookies = new RequestCookies(request.headers);
console.log(cookies[Symbol.for('edge-runtime.inspect.custom')]());
// "RequestCookies {"session":"abc123","theme":"dark","lang":"en"}"

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

interface RequestCookie {
  /** Cookie name */
  name: string;
  /** Cookie value */
  value: string;
}