@persist-kit/cookies

A primitive, pluggable cookie store implementing the standard Storage interface — the same shape as localStorage / sessionStorage.

• Zero dependencies
• ~1 KB, no Proxy, no event system, no magic
• Pluggable: bring your own document (SSR/tests), encoder/decoder, and namespace
• 100% TypeScript, fully typed

Install

npm install @persist-kit/cookies

Usage

import { CookieStorage } from "@persist-kit/cookies";

const store = new CookieStorage({
  prefix: "app_",
  defaultOptions: { path: "/", sameSite: "Lax", secure: true },
});

store.setItem("theme", "dark");
store.getItem("theme");      // "dark"
store.hasItem("theme");      // true
store.length;                // 1

store.removeItem("theme");
store.clear();                // removes every key under the "app_" prefix

Per-call options override the instance's defaultOptions:

store.setItem("session", token, { maxAge: 60 * 60, secure: true });

API

new CookieStorage(options?)

| Option | Type | Default | Description | | ----------------- | ----------------------------------------- | ------------------------ | ------------ | | prefix | string | "" | Prepended to every key, so multiple stores can share one cookie jar without colliding. | | defaultOptions | CookieOptions | {} | Cookie attributes applied to every write; can be overridden per call. | | document | { cookie: string } | globalThis.document | Inject a mock for SSR or tests. When omitted and no document exists, the store becomes a safe no-op. | | encode | (raw: string) => string | encodeURIComponent | Applied to keys and values before writing. | | decode | (encoded: string) => string | decodeURIComponent | Applied to keys and values after reading. |

Instance methods

Implements the standard Storage interface:

• getItem(key): string | null
• setItem(key, value, options?): void
• removeItem(key, options?): void
• clear(): void
• key(index): string | null
• length: number (getter)

Plus one convenience method:

• hasItem(key): boolean

CookieOptions

interface CookieOptions {
  path?: string;
  domain?: string;
  expires?: Date;
  maxAge?: number;      // takes precedence over `expires` when both are set
  secure?: boolean;
  sameSite?: "Strict" | "Lax" | "None";
}

Standalone utilities

The parsing/serialization primitives are exported too, in case you just need to read or build a cookie string without an instance:

import { parseCookies, serializeCookie } from "@persist-kit/cookies";

parseCookies(document.cookie);              // { theme: "dark", ... }
serializeCookie("theme", "dark", { path: "/" }); // "theme=dark;path=/"

SSR & testing

Pass any object with a cookie: string property — reads see the current value, writes are handed back to you:

const mockDoc = { cookie: "" };
const store = new CookieStorage({ document: mockDoc });

store.setItem("x", "1");
mockDoc.cookie; // "x=1"

If no document is available (e.g. Node without a mock) and none is injected, reads return null and writes are silently skipped — no errors, no crashes.

Namespacing multiple stores

Because every key is prefixed, two CookieStorage instances can safely share the same cookie jar:

const app = new CookieStorage({ prefix: "app_" });
const admin = new CookieStorage({ prefix: "admin_" });

app.setItem("theme", "dark");
admin.setItem("theme", "light");

app.getItem("theme");   // "dark"
admin.getItem("theme"); // "light"
app.clear();             // only removes "app_"-prefixed cookies

Notes on cookies as storage

• Cookies are sent with every matching HTTP request — keep values small. This package warns to the console when a single cookie exceeds the RFC 6265 practical limit of 4096 bytes.
• HttpOnly is intentionally not exposed as an option: it can only be set by a server response header, never from document.cookie, so offering it here would be misleading.
• This package does not attempt to serialize objects, chunk oversized values, or manage cookie consent — compose those concerns on top if you need them.

License

MIT